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While Java"^ is a hot new language for creating great 
Internet applications^ harnessing Its potential can be 
frustrating. But now with Microsoff^ Visual J^-h" 
development software, you can take full advantage of 
the Java language within the proven development 
environment of Microsoft's Visual Tools. 

Visual features the fastest Java compiler, 
translating over 10,000 lines of code per second. The 


visual debugger includes many industrial- 
strength capabilities, such as simultaneously 
manipulating multiple applets from within 
your browser. Wizards provide step-by-step 
assistance to rapidly create sophisticated applets and 
ActiveX^" controls. And, everything you build will run 
on multiple platforms and operating systems including 
Appie^ and UNfX.^ 



@19S6 Microsoft Corporation. All rIgMs reserved. Microsoft and Visual C++ are registered trademarks and VIsaal J++, ActiveX and Wtiew do yoti ward to go today? are tradecnarks of 
S:30PM. 3uridaiyt 8:OQAM ^ T;0(1PM+ TT/TPD available at {8CIQ} B32-$234. Cirtelde the U3 and Canada, contact yiHii local subsidiary. 
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Visual improves Java development by making It 
easier With it^ you can play a video or audio file with 
just one tine of code instead of hours of coding and 
debugging. You can aiso integrate thousands of exist¬ 
ing ActiveX controls to take advantage of desktop 
technologies over the Net. 

For data accesSf Visual J-f+ provides SQL processing 
using Data Access Objects (DAO) and Remote Data 


Where do you want to go today? 


Objects (RDO), so you can pick the best method based 
on your application’s requirements. And If you’re famlilar 
with the Visual development system, the Visual 
J+-K IDE should make you feel right at home. 

lOfOOO lines of code? No problem. Be with you in 
just a second. To find out more about VIsuai visit 
http://www.microsoft.com/visuaij/ or cail 
(800) 621-7930, Dept. A804* 

Microsoft 

www.mlcrosoft.com/visualj/ 


Microsoft Corporation. All other tradomarks are the pfoperty of their respective owners. * In the US and Canadai Monday - Friday. 7;00AM to mididght Eastern time. Sabirr^y. SiOOAM 





























Tired of programming in raw awt and vectors? 

Looking for a good tree, grid or tab widget? 

Take a look at these hot new Java products from Rogue Wave Software. 


The First Tools to Ins 

;tall after Your Java IDE 




“J Factory did everythir^ Ro^ue Wave said It would. 
After a short learnir^ period (less tiian 2ftjll days), 1 
was creartir^... applets and applications ... and 
having fun while doing it " 

Bill Rowley, PhiladalphLa Java Users’ Group 
rowleyv^© ix.notcom.com 


JFactoiy 




The Original Java 
GUI BUILDER 

You don’t have to be a 
java.awt expert to prototype and build your user 
interface with JFactory, Place buttons, panes, scroll 
bars, and even image loops into your applica¬ 
tion without writing a single line of 
code.Version 1.1 adds a bigger palette, nest¬ 
ed controls, a grid widget, enhanced font 
and color control, and more! 

Fnliance and reline your LI I with custom Java 
code that you write by combining JFactory with 
your JDK. Rest assured that JFactory s “protect 
blocks” will preserve your custom ccxle. 

Add your own objects to JFactory’s object library 
and reuse them in other apps. Use this capability to 

save coding time 


and effort while 
giving your com¬ 
pany’s applications 
a consistent look 
and feel. 

JFactory is avail¬ 
able now on Win 
95, Win NT, 

OS/2, Solaris, and 
HP-UX. 








JWidgets 2.0 

Deliver Great-Looking 
APPS—FAST! 

Jump start your interface develo]?- 
meni by using tJie defaults we 
provide widi each widget or by 
extending the classes via their public 



interfaces. The grid widget makes it so easy to 
display and manage tabular data on-screen that it 
alone is wordi the product price. Group box, 
tool bar, tabbed dialog, 
tree control, animation 
and mcjre r(jund out tliis 
IDE-independent Library. 


-JTools 1.0 
Essential tools 
FOR Java Development 

Start with a solid, tested foujidation for your Java 
a[>plications anti a]>plets. JTools complements 
java.util and java.lang with two powerful pack^ 
ages. The format package prrwides classes that 
facilitate formatted text and numeric output. The 
tools package provides fundamental data struc¬ 
tures and utility classes, including a regular 
expression class, eight essential ctjllection class¬ 
es, and tw'o interfaces dial allovv you to use the 
collections generically. 

'JMoney 2.0 
The Precision You Need for 
BUSINESS applications 

Precision arithmetic and built-in tin and al calcu¬ 
lations make J Money a must for numerical apph' 
cations. The numeric cla.sse.s give you rounding 
control anti convenient error handling, and arc 
faster and more complete than those found in 
java. sql.Numeric. The finance packages include 
annuities, loans, time value cakulations, and 
depreciation classes. 


Grid (Table) 
Anlmatfon 
Animated 
Button 
Group Box 
Tabbed Dialog 
Image Handlers 
Image Sutton 
Tool Bar 
Tree Control 
Progress Bar 
Status Bar 


RegExp 

BTree 

BTree Dictionary 

Slist 

Dlist 

Queue 

Binary Tree 

Set 

Bag 

NunaeHcFormat 
TextAlignment 
NumericPicture 
TextPicture 
Quick Format 


Humeric 15 

HumericError 

Defau ItErrorHand ler 

Annuity 

Loan 

Time Value 
Asset 

Warehouse 

Depreciatton 




The Software Parts Company” 




Rogue Wave 
products arc now 
available for 
purchasing and 
downloading at 
(jur web site. 


Surf Us 

http fwww, rogue wave.co m 


^Call Us 
(800) 487-32IT 
or(S4l) 754-5010 


OFax Us 
(541) 757^6650 



Rogue Is g regislurod iradoiriarK of RoguD W^ve Software, 4nc. Java is a traEfemark of 
Sun Mjcfosys^Hins. All oUibi tractemajls ara the property of Rogue Wave St]ttviar& or Ihar 
rEspedivB Iwkters. 
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FEATURES 


Java User-Interface Design 7 

by Jeffrey Kay 

IBM's infoMarket is one of the first major web-based 
search services to implement a user interface written 
entirely in Java. Jeffrey discusses its design and 
presents some of the Java classes that make it work, 

Server-Side JavaScript 13 

by Siidbakar Ramakrisbnan 

JavaScript is an object-oriented scripting language that 
can be written within specified tags and embedded 
within an HTML document. Additionally, "server-side” 
JavaScript lets you develop applications that execute 
on die server. 

Combining Visual Development 
Environments 23 

by Wm. Fliis Oglesby 

dur author mixes and matches the best features from 
Rogue Wave's JFactory and Symantec's Caf6 to create 
his JavaTax applet, web-based software for tax 
preparation. 

Calling Native Code from Java 27 

Robi Khan 

The downside of native Java code is that it is 
nonportable. On the upside, however* native code is 
sometimes the only way of getting the job done. Robi 
uses native code to implement a Java Clipboard class 
for Win32. 

Java and Embedded 

Real-Time Control 34 

by Kelvin Nilsen 

In the beginning* Java was intended for embedded- 
systems development. Kelvin describes the extensions 
and libraries you need to tnake this possible with 
today’s Java implementations, 

JavaOS: An Operating System for 
Small Devices 39 

by Steve Mann 

JavaOS is a complete operating system with a 
minimalist set of application and network services 
that can fit in a PDA-size memory footprint, Steve 
examines the operating system* and provides an 
overview of the upcoming JavaChips. 



Ramblings in Real Time 43 

h}> Michael Abrash 

Michael reveals how he and other id programmers 
designed and implemented tiie Quake lighting model 
which draws the world. In doing so, Michael focuses 
on performance and complex lighting. 

20/20 50 

byAl Williams 

ActiveX controls can be used with Visual Basic, 

Visual C++, Delphi, and many other environments. A1 
shows you how to use MFC to write custom controls. 

DTACK Revisited 58 

by Hal W. Harclenbergb 

Will web servers revitalize die SMP (symmetrical 
multiprocessing) market? Hal examines SMP’s 
chances for success. 

Software and the Law 61 

by Marc E. Brown 

Tliere's more involved in doing business on the Net 
than hanging a virtual shingle, Marc examines the 
promise and pitfalls of business on the web. 

Editorial 4 

by Tim Kientzle 


PROGRAMMER'S SERVICES 


As a service to our readers, all source code is available 
on a single disk and online. To order the disk, send 
$14-95 (California residenLs add sales lax) to Dr. Dobb's 
Journal, 411 Borel Ave., San Mateo, CA 94402, call 415- 
655-4100 x5701, or use your credit card to order by fax, 
415-358-9749. Specify issue number and disk format. 
Code is also available through the DDJ Forum on 
CompuServ'e (type GO DDJX via anonymous FTP from 
site ftp.mv.com(192.80.84.3) In the /pub/ddj directory* 
and through DDJ Online, a free service accessible via 
direct dial at 415-358-8857 (14.4 kbps, 8-N-l). 


Dr. Dobb^s Sourcebook., NovemherlDecemher 1996 
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W ouldn’t it be great if, instead of spending time and money testing your programs, 
you could just have a few hundred thousand eager, savvy users test them for 
you? It would be better yet, of course, if some of those users would fix the bugs 
they find. 

Some devebpers have realized this dream. They place their source code on the Internet, 
announce it in a few newsgroups, and wait for people to download, tesh and ev'en fix their 
programs. Tlie Free Sofi^ure Foundation’s highly respected GCC compiler and Emacs edi¬ 
tor were developed in this fashion. Free operating systems—linux, FreeBSD, the GNU 
HURD, and die like— have also benefited from generously contributed error reports and 
bug fixes. It's "'no secrets ■ attitude about sourc'e code has !^me definite advantages For 
their clients: Some people consider Linux more secure than many commercial operating 
systems because its source code has bem more widely scrutinized. This belief underlines 
an important point: Tliough free, these programs are not toys. They are laige, complex 
projects diat rival die .stability and feature lists of their commercial counterparts. 

In fact, development strategies for free software have been so successful that commer¬ 
cial developers are beginning to emulate them. It’s becoming common for companies to 
release beta-test software over the Web. Even IBM, once dominated by a prcjprietary, 
inward-looking worldview, has set up a special web site {http://www'.alphawork.s.ihm 
.com) specifically to disseminate prerelease software and elicit feedback. The news- 
making Netscape versus Miaosoft '‘browser war"* is also hemg fought with freely down¬ 
loadable beta .software. Development-tool vendors, like neologic, Rogue Wave, Borland, 
and even Microsoft, now include full source code with dieir development libraries. 

Caldera (http://www.caldera.com) has Lakc^ this free software-development mcxlel 
especially seriously. Tile company has managed to improve its software extensively by 
soliciting source contributions over die Internet, Because die Caldera Nemork Desktop is 
based on Linux, there's an abundance of uilented developers eager to contribute .sophisti¬ 
cated features. Many of these contributors ask for litde more than a copy of the softw^are 
and a T-shirt in return. As they contribute improvements to die wider Linux community, 
Caldera is generating a lot of gcKxl will (and press), as well as helping tt> encourage non- 
Caidera development that direcdy tiencfiLs Caldera. 

This strategy has been so successful that Gildera is going to try to duplicate the Linux 
phenomenon w'idi DR-EXDS. Caldera recently obtained a collection of IXJJi technologies 
from Novell, including CP/M, DR-D05, PalniDOS, Multi-User DOS, and Novell 1X)S 7, 
Caldera plans to add a variety of new features to diis base and release a new OpenDOS 
operating .system. To encourage use, it plans to past the source ctxle on iLs web site. 

Some of the code will e\^entually be released under die GNU General Public License 
(GPL). This means that those portions will lx- freely available to wliome\er wants to use 
them, and it emsures that Caldera (and everyone else) will lx able to use iiny improve¬ 
ments other people niiglu make to tliat code, 

Anodier company using free software to iLs advantage is Cygnus (htlp://www^cygnus. 
com). It started by supporting GNU GCC and other Free Software Founckilion tools, 
Cygnus customizes and extends these tools for clienLs, improving tile freely available ver¬ 
sions in the process. For many Cygnus clients, it's an ideal situation. The software is stable 
and high-quality, with good support. Just as importandy, since the software is free, clients 
aren't locked into a single vendor. Even if Cygnus were to .suddenly stop supporting a 
particular tool, the client would liave full .source and could contraa with .someone else. 

The franiers of die GNU GPL (http://www.gnu.oig) might kx)k upon the .success of 
Caldera and Cygnus as Ixkig a prelude to an er:i in wliich all software is free, and com¬ 
panies compete for support and maintenance servic’es. I don't believe diis will happen; 
commercial software isn’t going to go away. However, free software isn’t going to disap¬ 
pear either. As commercial development hudgeus and schedules tigliien, anyone who can 
develop software for free (or nearly free) deserves to lx taken .seriou.sly. 
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With the High Speed CodeBase Database Engine 


Wouldn’t it be great if there was a single CiS'tBbSSS 
engine that gave you the flexibility to use any of your 
favorite prt^ramming languages, including the hot new 
C, C-E+, Visual Basic and Delphi? 

Of course to be worthwhile, it would have to be a lot faster 
than the built-in database support that comes with most of 
these languages. In Java's case, it would also have to be 
compact enough to download quickly in a web applet. 


So the question is, what solar system 
do you have to travel to in order to find such a product? 
(hint: not as far as you think) 

That’s right, you can get it right here on earth with the new 
CodeBase® 6 database engine from Sequiter Software® This 
multiple award-winning product is simply the 
best database engine on the market, and it leverages your 
programming skills like no other product. 
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Award-)^nningperformance 5year^ m a row! 


The best part of all, is that this technology is incredibly 
affordable, and includes full source code and 
royalty free distribution. 


xBase compatibility would be nice too, 

considering it is still the most widely-^used data file format in 
the world today And not just file compatibility but multi-user 
locking compatibility as well, so you could keep your 
investment in existing FoxPro, dBASE and Clipper apps. 

OK, this is stretching it a bit, but if it supported both 
multi-user and client/server models, and was 
portable across any operating system on the planet, 
that would be way too cool. And that client/server thing is 
looking really important as the Internet continues 
to integrate itself with the desktop. 



Vie Database Engine for Pivgnmmers 


So get busy and 

give us a call 

We’ll tell you about 
a few more goodies, 
and also how you can 
take CodeBase for a 
free 30 day test spin. 

403 - 437-2410 

SEQUITER III Fax: 403'43G-29S9 
SOfTWARE INC. Ill Email: in1oesaquctflr.com 


Olfl^^Sequttw SoHwarahG. /Jlitahftnawtwd. CotSa6o» arid m ,AI olh*r oiwSip::J iWi« a* IrodsixBla 11^ «(ti6clh?e mm RO a)* 7H at«rtitt!l ISH 03840 


Wfetj 9jte: www.set^flerixim 


CIRCLE NO. 105 ON READER SERVICE CARD 
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Developers Beware: It's embedded in your systems - and it is growing. The Unicode Standard, 
the industry workhorse of multi-lingual support, forges ahead. Version 2.0, with all current 
additions and updates, is now at large. Don't be obsolete. Buy the book. 



When the world wants to talk, it speaks Unicode 


http;//www,u HI code.org 
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Java User-Interface 
Design 


I BM infoMarket is one of the first ma¬ 
jor web-based search services to im¬ 
plement a user interface written en¬ 
tirely in Java. This Java interface 
accomplLshes two tilings. First, it pro 
vides advanced capabilities similar to those 
available in stand-alone applications. Sec¬ 
ond, the software demonstrates Java's ca¬ 
pabilities in a serious and signiftcani ap¬ 
plication. Some of the most interesting 
java software on the Internet is present¬ 
ed as more of a window decoration than 
a primar}^ interface. This Java interface 
brings users functionalir>' previously found 
only in software natively installed on the 
users’ computers. 

IBM infoMarket (http://www.infomar- 
ket.ibm.com/) lets users search multiple 
source databases simultaneously. These 
databases are categorized by subjea area 
and name, providing a w^ay to select which 
sources are searched. Users may perform 
simple searches by entering keyw ords or 
enter a more-advanced Boolean 
query'. The search results in a “hit’" 
list that returns the title of the con¬ 
tent, an exhibit, date, author, rele¬ 
vance rank, and price. 

The original IBM infoMarket in¬ 
terface uses HTML forms. Tlie sim¬ 
ple search screen includes an edit 
box for keywords and the source list 
coded as a series of check-box list 
elements. 'Fhe search retum.s a hit list 
as an HTML page, 25 liits at a time. 

The original interface, including the 
generation of the search screen, 
source list, hit list, and user-request¬ 
ed data reductions, is implemented 
almast entirely as CGI scripts. 

While HTML and CGI comprise a 
viable approach, a more interactive in¬ 
terface enhances usability. The HTML 
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version requires users to page forward and 
backward to refme a query because the 
search page and the results page are sep¬ 
arate. And because the results are all page 
oriented, the hit list is limited to a quantity 
that Ls reasonably visible on a screen. 

The design goals of the Java version 
were to improve the overaU usability and 
to increase funaionality, Tlie hierarchical 
nature of tlie sources Is easily represent- 
ed by a hierarchical Hstbox with expand¬ 


ing and collapsing entries. Tliis listbox al¬ 
lows users to see just topic areas or to 
delve deeper into the available sources 
for a particular topic area. Users can even 
mix and match topic areas and particular 
sources if it makes sense for a query. 

Users can experiment with different 
ways of formulating queries by toggling 
betweoi the simple search and advanced 
search. Tlie search-entry fields retain the 
terms as users try different searches to see 
which results in the best liit list. 

By displaying the results as a multi- 
column listbox or grid control, users can 
access a wider range of functions, in¬ 
cluding sorting and selecting. In addition, 
a multicdumn listbox can hold many more 
lines than might make sen.se for HTML- 
based output. 

In the end, the user interface should 
adopt the style of most interaaive appli¬ 
cations, witli tlie search query, source list, 
and resulLs list residing on the same screen. 
Users then have all of the infomia- 
tion in view when searching. 

Figure 1 is the enhanced, Java- 
based IBM infoMaiket user interface. 
The search-word entry portion of 
the window^ flips between the sim¬ 
ple search and the adv^anced search. 
This source list appears to the right 
in an expanding and collapsing en¬ 
try listbox, file resute are in the to¬ 
tem part of the panel in a single 
multicolumn listbox. In the center 
of the listbox are the buttons used 
to control Ihe operations and a mes¬ 
sage label indicating the status of 
the operation, 

Basic Applet Structure 

The basic applet structure is a sin¬ 
gle flow from the entry of search 
terms to die review of results. The 
interface to the web server is im¬ 
plemented through CGI scripts. In 
early implementations, a CGI scrip! 



Dr, Dobbh Sourcebook^ NouemberlDetember 1996 


7 













JAVA Ul 


parsed the HTML pages returned by our 
production system, but iaier versions of 
the software use CGT scripts that return 
“raw" output in a format easily parsed in 
the Java code. All CGI interfaces are im¬ 
plemented using tlie GtT method to avoid 
the additional code necessary to imple¬ 
ment a POST in Java. 

The sources listbox is a derivation of 
the standard Java listBox class. The list- 
lx)x keeps track of which list elements are 
expandable and which are not. In addi¬ 
tion, tlie titles of the sources are matched 
with the terms that are returned as part 
of the CGI call to tlie web server when 
executing a search. 

The entire screen display is imple¬ 
mented using a series of panels, 'fhe 
outermost panel and all but two of the 
inner piinels use tlie Man¬ 

ager Although it is the most ccjinplical- 
eel layout manager in the Java Abstract 
Windows Toolkit (AWT), the CirkJ- 
Baglayout Manager is also the most func¬ 
tional when die user interface requires 
precise layout instructions, U allows each 
component in the panel to be placed 
precisely with respect to its neigiiliors. 
The only panels that do not use the 
CridBagLayoiit are the Message panel 
(BorderlMyout) and the Button panel 
(FlowLa^wil). Figure 2 shows each of the 
panels in tlie display. 

T{> easily switch beiw'cen die simple 
and advanced search options, each cmiry 
.screen is huilt into a .separate panel. Wlien 
pressing the toggle button (designated 
‘"Simple .seardi” or ‘'Advanced seaich’* de¬ 


pending on what is currendy displayed), 
the applet quickly rebuilds die interface 
using the appropriate display panel. The 
rebuilding of the display is also aided by 
having each of die main interface com¬ 
ponents in its own panel, reducing the 
complexity of the code. Figure 3 is a sub¬ 
section of the search screen with the 
advanced-search panel visible. 

Threads 

Threads play a minor role in die applet, 
implenienting the “cancel search’’ func¬ 
tionality and the asynchronous collection 
of status infoimadon during a search. The 
use of threads allows the applet to per¬ 
form some minor functions without pol¬ 
luting object encapsulations in the code. 

The cancel seamh function u.ses a tliread 
to allow the search operation to lun inde- 
pendendy. The applet can tlien condnue 
pjXK'essing messages in die message queue, 
a necessaty^ funaion when user input is re¬ 
quired. Wlien a seaadi starts (a u.ser pre,s.s- 
es die ‘‘Search" button), die search diread 
starts tind the Search button Ls redded “Can¬ 
cel search." All other buttons are disabled. 
If die Cancel search iiution is pressed, the 
search thread is stopped using a 
Threadskipf) funaion call 

The status functionality is implemenred 
in a similar fashion. The search code is 
fully encapsulated in a single object, a 
derivadon of the multicolumn listbox class. 
Tliat class initiates the search CGI call, re¬ 
trieves the results, and displays them. Tlie 
.search thread, while running, polls that 
object every half second to find out h<w 


many elements it currendy has in the list. 
This mediod informs the user that some¬ 
thing is happening while the search re¬ 
sults are retrieved, and does not burden 
the Java applet significantly. 

The Multkolumn Lisfbox 

The most interesting class in the applet is 
the multicolumn listbox {MCList). Wiiilc 
not the most ideal or efficient implemen¬ 
tation of a basic grid control, die code em¬ 
ploys many of the more subde Java lan¬ 
guage elements. In particular, a C++ 
software developer may not be familiar 
with some of these tecliniques because 
they are unavailable in C++. It is also die 
one place in tlie code that extensive work 
had to be done to ensure compatibility’ 
across platforms. 

Tlie multicolumn listbox is implement¬ 
ed as the public class MCList (available 
electronically, see “Programmer s Servic'es," 
page 3), which encapsulates three .sub- 
components; horizontal and vertical scroU 
bars iMCScmUijar) and MCCanim, an ex¬ 
tension of the Carwas class. In addition, 
two public interface classes allow a de¬ 
veloper to implement “owner-drawing” 
and “owner-defined sorting" objects tliat 
can be used in a cell. 

NiCLhf 

MCList Ls an extension of the Panel class 
that implements many of die “pass- 
through" function calls. Since most of the 
functionality of the class resides in MC- 
Cam)as^ MCList must expense certain func¬ 
tion calls to provide a single interface 
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Figure 1: IBM infoMarket sendee Jam search screen. 


8 
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point. An allernate approach would have 
been to build most of the functionality 
into MCList direaiy, but the encapsulation 
of the drawing routines in the MCCanvas 
class reduces the complexity of tlie code 
and takes advantage of the layout capa¬ 
bilities in Java. The constructors in MCList 
set up the number of rows and columns 
that die listlxDX must initially display. While 
the number of rows is variable, there are 
no provisions in this implen>entation to 
add cc^umns. The mtida^) and setForU() 
functions have been overridden to ensure 
tfiat the horizontal scroU bar limits are set 
properly. Tiie vertical scroll lyar incrcmoiLs 
by row cotint rather than pixel cx>uni, so 
its limits are only updated when the row 
count changes. 

MCScro/Zbar 

Perhaps tlie most frustrating thing about 
Java is its relative infancy, MCScroUbar is 
a class designed to address just that issue. 
Because of the variations in Java imple- 
mentations, the limits and line- and page- 
increment values of the default scroll bars 
were inconsistent. To work around these 
problenxs, tlie MCScroUbar overrides 
several of the Scrollbar functions and 
replaces tliem with equivalent functions 
that work better across platforms. 

MCPo/nfobfe and MCSorfcrbJe 
Interface Classes 

Interface classes define functional inter¬ 
faces that allow an object to provide func¬ 
tionality without having to define a new 
superclass. Specifically, the MCSortabie 
and MCPaintable interface classes (List- 
ings One and Two, respectively ^ listings 
begin on page 11) allow an object stored 
in a cell to provide functions lor painting 
and sorting itself even though the object's 
base class is These classes are used 

to display the icon in the header row, to 
draw the description column with bold 
and plain fonts, and to sort columns al¬ 
pha betically or numerically. Tlie MCLm- 
%jeand TitieAbstract private class¬ 

es implemented as part of the main 
program, demonstrate the use of tiiese 
classes (Listing Three). 


The MClmage class defines an exten¬ 
sion to the Object class dial implements 
MCPaintuble to draw a picture in a cell 
area. The MCPaintable class requires that 
the paintf ) function be implemented 
which in this case jast draws the image on 
the supplied Grcpbtcs object. Because tlie 
class is derived from the base Object class, 
it can be used as tlie contents of a cell. 

The TitieAhstract class is more compli¬ 
cated implementing IxJtli the MCPaintable 
and MCSortabk interfaces. This is as cbse 
to multiple inheritance as Java pennlLs. The 
TitkAbstract class extends Object (as re¬ 
quired for use with MCList) and imple- 
nx^nts the toStringO function to return an 
appropriate value. The paintO function 
draws the title string in Lidd wliile the ab¬ 
stract part Is drawn using a plain text face. 
The lessthanO and greaterthan() func¬ 
tions compare the joined title and abstract 
to the string value of any other object. 

MCCanvas 

MCCanvas is the centerpiece of the multi- 
column listbox. It draws the rows and 
maintains the values of the cells. Each cell 
value must be derived from the Object 
class and aU values are stored in Vectors, 
one per column. The column headers are 
also stared in a single Vector md one ad¬ 
ditional Vector Ls defined to store the sort 
index. Because the widths of the columns 
are fixed, a single array of integers is de¬ 
fined to hold the width of each column. 
The widtli of a column is defined in char- 
aaers based on the average width of the 
characters in the selected font 

As rows are added, cell values are set 
to zero-length Strings. Tlie cell values are 
set individually using tiie setValue( ) func¬ 
tion, where the arguments are the row, 
the cdumn, and tlie Object to be stored 
in the cell. As cells are set, they are paint¬ 
ed using the paintCelK) function. This 
function is allied directly, rather than us¬ 
ing a repaintO call, to update the display 
synchronously. 

The paintf) function itself is split into 
several function calls so tliat individual 
parts of the display can he drawn as need¬ 
ed or as part of a global update. The 
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Get Your 
Algorithms Here 


Dp. D^*s Essential Books on 

Algorithms and Data 
Structures CD-ROM 

There’s nothing more fundamental to 
programming than algorithms and data 
structunss. Your CD-ROM includes eight of the 
most important books ever written for program¬ 
mers about the subject 

These books give you proven and trusted ways 
to ar^alyze and solve problems in Cf C++, and 
other languages. Take advantage of the 
research and testing that went Into devebptng 
the algorithms and data structures included on 
this CD-ROM! 

Master practical programming techniques. 
Ensure that your programs are undenstandable, 
maintainabler and effident—even as they grow 
in size. The right data stmcture can make your 
operations simple and effident, the wrong one 
can make an operation cumbersome. 

Learn from the experts. Set up your aigorithms 
the right way the first bme-Ujefore you ever 
write that first line of code! 

Your CD-ROM comes with these must-have 
features: 

• Boolean, Full-Text search engine locates infor¬ 
mation fast across all or selected books. 

• Hyperlinked Indexes and Table of Contents 
jump to topics, 

• Includes copy/paste. print, save-as, book¬ 
mark, and note(s) functions. 

• Plus much more! 

Buy your CD-ROM today for only 

$B8.85I 


Includes These 8 Essential Books 


Chosen by tbe 
Data Structures; From 
Arrays to Priority Queues 
by Wayne Amsbury 

htroduction to A/goritbms 
by Thomas H. Cormen, 
Charles E. Leiserson, and 
Ronald L Rivest 

/nformotion Retrievot 
Data Structures 
&£ Aigorkhtn^ 
edited by William B. 
Fraiees and Ricardo 
Baeia-Yates 

Rdsabk Data Structures in C 
by Thomas Plum 


Editors of OOJ: 

fmdcimentate of Doto 
Structures 
by Ellis HoTX>witz 
and Sartaj SahnI 

Data Structures md 
Algorithm And/ysis ih C 
by Mark Allen Weiss 

Pmcdcai Doto Struaures 
in C++ by Bryan Fiamig 

Data Structures, Algorithms 
and Program Styte Using' C 
by James F. Korsh and 
Leonard J. Garrett 


Call: 800-351-4544 
Fax: 913-841-2624 
E-mail; orders^mfLcom 
Int'li Use mailr fax, e-mail, 
or call 913-841-1631 

Go to our website for more 
product information: 
ww w.d dj.com/cdrom/ 


Mail orders: 1601 West 23rd St., Ste. 200 
Lawrence, KS 66046-2700 USA 


Figure 3: Subsection of search screen shotmng advanced search panel. 
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paintC) function calls the drawing rou- 
tines for all of the display components: 

• paintHeader^O paints the header row 

of the listbox. 

• painlRowC) paints a single row of the 

display. 

• paintCelK) paints a single cell. 

The painiHeaders() function doe,s not 
call paintCelK) diough paintCeU() 
duplicates much of painiHead^ func¬ 
tionality. The pmntHeaders() function 
does some additional manipulation of the 
cell contents before it Ls displayed (it adds 
to the primary sort-cciumn header), 
preventing the use of painlCelK ) in its 
present form. 

The paintCelK) funaion draws the con¬ 
tents of each celL Because of the possi¬ 
bility of a cell implementing its i>wn paint¬ 
ing routine, paintCeiiO must check the 
object before it is drawn lo see if it im¬ 
plements the MCPainlahie interface class. 
It does this using the imlanceof 
an operator dial c’an test the object to see 
what classes it instantiates. If the object Is 
an instance of the MCPainlahie class, it Ls 
reLnst and its l^ainK) hmcLkm is called. If 
the object is just a string, it is aulomati- 
cally fit into the cell area using worI wrap¬ 
ping. Figure 4, an exeerpt from painl- 
Celk), shows this code, 

Tlie paintCelif) function uses the 
createi) method of the Graphics class to 
create subsections for drawing, 'lliis Ls re¬ 
quired because only one clipping rect¬ 
angle can be eslal^lished for a Graphics 
object. When pahUCelK ) is called, a new 
Graphics objea is created based on the 
original object. This new Graph¬ 

ics object clips to die dimensions of the 
cell and Ls used for all subsequent graph¬ 
ics operations. 

Sorting is Implemented in MCCanvas 
using a low-tech insertit>n sort. Though 
diere are many container classes [provid¬ 
ed with Java, no sorting functions are 
provided. The sorii) function is called 
expiicidy by the owner of the MCList ob¬ 
ject, During a sort, each object is tested 
with instaneeqf to see if it implements 
MCSortahle, if it does, die lessthani ) and 
greaterlhan( ) functions of MCSoriahie 
are used for comparisons, if not, the ol> 
jeci is sorted based on tiie value of the 
toSiringi ) function. 


Lessons Learned 

t encountered several problems using Java 
as a development language and environ¬ 
ment. The good news, however, is that 
these are not irdierenl problems; almost 
all stem from Java’s relative immaturity. 
As Java matures, many of these problems 
should go away. 

The development platform was the 
Java Development Kit (JDK) Version L02 
under Windows 95 with Netscape Nav¬ 
igator as the target platfonn. I wrote all 
of the code by hand using an editor and 
a make program, and used the JDK 
Appletviewer for development testing. 
When it became apparent that Navigator 
and the JDK Apple [viewer did not func¬ 
tion exactly the same, I was forced to 
use Navigator more extensively and ear¬ 
lier in the process than I desired. In most 
cases, tlie Appletviewer did a better job 
displaying die applet than Netscape Nav¬ 
igator. 

Netscapie Navigator 2.02 showed symp¬ 
toms of memory problems. When the 
multicolumn listbox reached 100 ele¬ 
ments, Netscape Navigator crashed. As a 
result, I reset niy sights for Navigator 3 0 
and beyond. 

The show[J<}C2imeni( J function is the 
Java function Lliat retrieves dtx.:uments in 
tile scarcli-results list. Besrause of a bug in 
early Ix^tas of Navigator 3, any dtx^ument 
retrieved that w'a,s pR)ce,s.sed liy a helper 
application crashed the browser. 1 devel¬ 
oped a kludge using JavaScript. Instead of 
using the showDocumenif ) hinction di¬ 
rectly, showDocumenK ) calls a JavaScript 
hinctitm and passes die dtxument URL to 
dial funaion. This changed the call from 

sh owDoc u men i( ^hiip://xxx.xxx.xxx.xxx/ 

XXXJCXXV; 

to 

sbf)WlJ(}cUfmmlCjceusct-^d:sh{Atd(^^^ \ 'ht^i:// 

Of course, thLs prevented oilier bniwsers 
fR>m retrieving docunienLs, since only Nav¬ 
igator cunently iniplemcnLs JavaScript. Nav¬ 
igator 3.0 beta 5 cured iliis problem. 

Scroll bars continue to 1 k" a stiurce of 
frustration. Hach platform seems to have 
a different Idea about die scroll-bar lim¬ 
its and page- and line-increment values. 
Sotnt' iietas of Navigator had a liug that 
would not allow the page- and line- 


increment values to lie clianged from their 
defaults of 10 and 1, respectively. I cod¬ 
ed MCScrollhar to eliminate this incon¬ 
sistency by trapping most of the scroll- 
bar value sets. 

Double clicking on a Canvas also 
proved troublesome. T’he handleEvent() 
function in MCList lias several work¬ 
arounds to address this problem. This 
problem initially manifested itself on 
UNIX/X-Windows and Macintosh plat¬ 
forms, where the double click could not 
be trapped, hut even Navigator 3,0 beta 5 
for Windows 95 exhibited dtis problem. 
The initial workaround counted 
Evenl.MOUSE_DOWN events, but thLs also 
proved mct:>nsislenL A second workaround 
counted Fvent.MOUSE_UP events and this 
worked lietter. There are still double-click 
profile ms on some filatforms. 

A strange problem with die setFont() 
function occurred while building the 
iminti) routine for the TitkAbsimet class* 
Apparently, tloing a setfontO wliile click¬ 
ing on a scroll bar could cause a thread 
(or the main thread) to freeze. I at¬ 
tempted to correct the problem by dis¬ 
abling the multicolumn listbox during 
screen painting. T his worked in most cas¬ 
es. Fortunately, it appears that lliis prob¬ 
lem lias vanislied from later beats of Nav¬ 
igator 3 0. 

Font problems across platforms also 
seem lo exist. Java uses die “a-point-a- 
pixel” mocleL One point equals one pix¬ 
el. On some Navigator implementations, 
the fcjni metric.s returned from a selected 
font were txrcasiunally incorreci, some¬ 
times even twice diat of ilie selected font 
TJie text on the screen looked okay and 
demonstrated that the system was re¬ 
turning the correct font size, but the font 
metrics that tile Java Virtual Machine re¬ 
turned were wrong. I found no particu¬ 
lar workanHind that was acceptable. 

On Navigator 3.0 beta 5, irivalidadng 
die windtiws did not always result in a 
repahnf) c'aW. I corrected diis by adding 
a repatriK ) call after die invalidatef ). In 
addition, to prevent flickering on screen 
updates, the upekUei )hmaion of a com- 
|ioneni is overridden to just call pamt( I 
This prevents die updatt^ ) function from 
clearing the component area. 

Conclusion 

The IBM infoMarket Java user interface 
demonstrates great potential as a prima¬ 
ry u.ser interface. It improves u.sahliity and 
increases functionality. As die Java envi¬ 
ronment matures, this user interface and 
others like it will drive die World Wide 
Web into the universe of interactive ap- 
plic-iitioas. 

DDJ 


if (values[col].elementAt(realRowCrow)) infitauceof HGFaintabIc) [ 
MCPaintable k = (MCPaintable)values[col]*elementAt{realRow{row)): 
s,paint(newg,this,widths[col]*aveWidth+Inset,Inset); 

} 


Figure 4: Code excerpt from paintCelK) sbounng the q/Tnslanceof, 
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Listing One 

iMpdrt jaVA.awt.*; 

iMport java.applflt,*: 
iaport java,uet.*; 
iMpDirt j ava, titil F *; 
lajHirt Jflva.io.'tf 

// Code is p]7QTided •'AS IS*' for exaiaple purposes only, Tiiithout warranty 
piihlic interface HCPaintable [ 

flbflliract void painty Graphics g. Object o.lnt width* int ijiaat); 

) 

Listing Two 

import javaFai#t.*E 
import java.awt.image.*j 
iraporc java.applet.*; 
impart javBFnot,*; 
impart javB.iitil.*: 
import java.lo.*; 

// Code provided "AS IS** for example purposes only* without warranty 
public interface MCSortable { 

abetract boolean lesstban(Chjact o); 
abstract boolean greaterthan (Object o): 


listing Three 

import jflva.awt.t; 
import javB.awt.image,*: 
impart jsve,applet.*; 
impart java.net.*j 
import java.util.*j 
import java.io,*: 

// Coda provided “AS IS** for example purposes only, without warranty 

dees HCInage extenda Object ImplamentH HCFdintahla t 
Tmege image; 

public KCIlnHge(Image C 
image = it 

] 

public void paint(Graphica g* Object o,Iiit widtb^int inaat) t 
If (g = null) return; 

If {o inatanceof tmageObsecver) [ 

g.drawlmage(imaga. inset,,(LmagaOhserver}o); 

J 

i 

public String toStringO t 
taturn "Cryptolopa": 

1 

clflsa TitleAhstract extends Object ImpletnentB HCFaintable, HCSortsble [ 
String Titla * 

String Abstract w 

public TltlaAhflttBCt(String t. String a) C 
Title - t: 

Abstract = a; 

3 

public String toStrijig(3 C 

return Titla + " « r Abetract; 

1 

public boolean lessthan(Object o) [ 

return toStringO .c{HiiparaTD(a.l:DString()} < 0; 

3 

public boolean greaterthan(Object d3 E 

return toStringO .compareTo(o.toString(}} > 0; 

} 

// void wcapStciiig(Grapbica g.String e.int w) 

public void paint(Graphics g* Object o,lnt width, int inset) ( 
if tg — null) return; 
width -* inret; 

if (width <= 0) return; // hidden row 
String temp - 
FontKetrics fra = null; 

Font f = g.getFmitO: 

inrt col = 0; // k coordinate 

int y = 0: // j coordinate 

int linahelght = 0; // llnehelght 

Font newFont = new Font(f.getHame (),Font.BOLD,f.getSize()]: 

for(int i=0;i<aii++) t 

StringTokenlzer et = null; 
if Ci ^ 0) C 

g.aetPont(nawFont): 

St » St cingTokeniaet(Title) ; 

fm = g.getFontHetrlcsO: 
y = ^fo.getHaxAscentO; 

J 

else C 

g .setFont(f); 

fm = g.getFoniJtetricsO: 


) 


St = new StringToltenizer (Abatract); 

3 

lioebaight fm.getMaxAscent f) + fa .getKaxCescentE); 
while (at.haaKoreTokenaO) C 

String tok = at.nextTbkenO ; 
if (temp ™ "”) [ 
temp ^ tok; 

1 

else { 

if (£TB.atringWidth(temp + " " + tok) < width - col) ( 
trap + to'ki 

3 


elee ( 

if {(col + fm.stringWidthCtempJ > width) && (col I” 0)J { 
col = 0; 

y llnebeighti 

if (fia.stringWidthttemp + " “ + tok) < width - col) { 
g.drawString(temp,col,y): 
col = ll: 

y linehaight; 
temp ■ tok* 

) 

) 

else { 

g .dtauSt ring (temp.ool+ineetFy); 
col " 0; 

y += linahelght; 
temp - tok: 


1 

1 

] 

if (temp I- i 

g.drswString(temp,col+inset,y): 
col += fii.atringWidtb(teHipJ+fn.etringWidth('’SX"): 
temp = ■"*; 
if (col > width) t 
col = 0; 

y += linehoight; 

I 

} 


End Listings 
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The l^mderm GUI 
Toll-Fnic: 

Teb 416 5?4-102fi Far; 4 i 6^594^ 1 919 
wehinfoHklgjiiqni yrww.klg.anm 
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\ 

Essential Java 
Components for 
Cool Web Sites and 
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complete Java table/grid control 
available. With 63i rKsnutccs, and 
dozens of methocis, LivcTable Pro is 
the easiest and fastest way to get 
your Java applications and 
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Netscape People 

MAKE AN IMPACT ^ 


INNOVATIVE! VISION! CREATIVE! CHALLENGE! COOL! 


IMPACT! 


The world sees a Ret/olution: The effect of the single largest infrastructure change on individuals across 
and within nations^, communitieSy and corporations, Netscape is setting the Pace: The fastest rate of adop¬ 
tion of technology and products that the computing world has seen, IMPACT! The potent result of a 
combination of your abilities and our products on the global frontier that is the World Wide Web, 


Core Technology Group 

'’Home of Java Development!" 

Join the Core Technology Group {CFG) 
in using your engineering skills developing 
a multitude of Java projects in one of the 
following areasi 

JavaScript Windows and/or Mac 
Engineer 

Design and develop the JavaScript 
platform on Windows 3.1, Win 95, NT 
and/or Mac platforms. Positions requires 
a BSCS or equivalent and 3+ years' 
building robust systems software on 
Windows and/or Mac platform. Experience 
with language runtime systems and/or 
language interpreters is a big plus. 

Java Security Engineer 

Development and maintenance of C & 
Java code to support "signing" of Java 
applets, providing authentication so that 
downloaded applets come uncorrupted 
and with property authorization from 
the server. Position requires a ESCS or 
equivalent, 5+ years' building robust 
systems software in C and/or C++. 
Experience with concepts & practices 
of certificate-based security systems is a 
big plus. 

Platform Engineers, 

Windows, UNIX and/or Mac 

Port and maintain the Java VM and 
runtime environment on the Windows, 
UNIX and/or Mac platforms. Position 
requires a BSCS or equivalent, 5+ years’ 
experience building robust Windows, 
UMX and/or Mac systems software in C 
and/or C++. Must have Windows, UNIX 
and/or Mac experience. Language run¬ 
times for interpreted languages and Java 
runtime environment are a big plus. 


java Back-end and Runtime 
Engineer 

Develop extensions of the Java virtual 
machine and execution environment. 
Depending on candidate, may be 
responsible for development of Java 
Platform compiler technology. Position 
requires a BSCS or equivalent, 5+ years* 
experience building robust systems 
software in C and/or C++. Experience 
with language runtime for interpreted 
languages and experience with compilation 
techniques for byte-code interpreted 
languages is a plus, 

Java QA Engineers 

EnsLire the excellent quality of Netscape's 
cutting-edge products. Your C, C++j 
HTML or Java programming experience 
on multiple platforms coupled with your 
3+ years' testing background experience 
are essential as you automate test cases, 
create guidelines of test, executitm, and 
perform focused investigation t}f product 
features, Youll work closely with the 
product development team throughout 
the product planning and creation 
prtKiess, 


JavaScript Manager 

You will manage and grow the 
JavaScript group reporting to the VP of 
the Core Technology Group. Candidate 
must have strong technical leadership 
capabilities, 15+ years' experience 
building sophisticated system software 
and 5+ years’ managing a sophisticated 
development group, and a BSCS or 
equivalent. Object-oriented technologies, 
language development, scripting, 
distributed cross platform systems software 
development is all considered an advantage. 



NETSCAPE 

Trademarks ajur r^ktered to their respective ciompanics. 


For further consideration, please note 
the job title of the position(s) you are 
interested in, and fax your resume to 
(415) 428-4072 (referencing DDS 
12/96). You may also e-mail your 
resume to resnme@iiets^cape,com. 

As a last resort, snailmail us at: 

Atm: People Dept., DDS 12/96; 501 
E. Middlefield Rd., Mountain View, 
CA 94043. 

Netscape is an equal opportunity 
employer. In addition, Netscape is 
committed to diversity, not only as a 
necessary business solution, but as a 
desirable pathway to the future. 
Netscape is also a really cool place 
to work! 

You can also check out our home 
page for a quick tour of Netscape 
and information about these and 
other open positions: 
hnpi//www.netscape.com, listed 
under Company information. 




























































JAVASCRIPT 


Server-Side JavaScript 


J ava Ls an object-oriented program¬ 
ming language that can be used to 
write portable applications diat are 
later compiled by tlie Java compil¬ 
er. The Java compiler generates b^e- 
codes for the Java Virtual Machine. An in¬ 
terpreter runs these Java applications using 
mn-time support (the Java run-time envi¬ 
ronment is provided with tlie Netscape 
and other browsers). When a Java appli¬ 
cation is embedded within a web page, it 
is known as an "applet.'" Writing applets 
requires programming experience. 

JavaScript, on the other hand, is an 
objea-oriented scripting language tliat can 
l:>e written witliin specified tags and em¬ 
bedded in an HTML document. It gives 
HTML authors the ability to write simple 
programs md scripts that interact witli web¬ 
page objects like forms, frames, and ap¬ 
plets, fn .short, JavaScript is neitlier a scaled- 
down version of Java nor a replacement 
for CGI scripts. It augments both. 

JavaScript is interpreted by the brow'ser 
from the source code. In contrast, Java ap¬ 
plets must be precompiled into a class be¬ 
fore use. JavaiMpt u.ses built-in extensible 
objects, but has no classes or inheritance. 
JavaScript data types are loosely typed; that 
is, you don’t have to specify a ty'pe 
for a variable. Moreover, object refer¬ 
ences are checked at am tin^ (dy¬ 
namic binding). 

Server-Side JovoScript 

LInderstanding serv^er-side JavaScript 
is central to devebping JavaScaipt ap- 
pUcarions. Server-side JavaScript is a 
language for devebping applicatioas 
that execute on the server. The 
Netscape live Wire de\^elopnient envi- 
roniTicTit con:^s with server extensions 
designed to w'ork with the Netscape 
Server API and to run as an integral 
part of Netscape servers, (Tilts discus- 


Sudhakar is a software-development 
engineerfor Informix Software's Ad- 
imiced Technology Group. He can 
he contacted at siidba®infonnixxom. 
This article is adapted from an arti¬ 
cle in TechNotes, an internal In- 
foTinix publication. 


Developing 

Netscape 

LiveWire 

applications 


Sudhakar Ramakrishnan 


sion is based on die Netscape IJveWire for 
Sun Solaris Betal dcxximentation.) The serv'- 
er extensions pro\ide the needed run- time 
interpreter to execute scripts on tlie server. 

Server-side JavaScript augments CGI 
programming and maintains clieit infor¬ 
mation acro.ss transactions. A predefmed 
set of objects is included for application 
development. Built-in Rinctions are also 
providcxl to enhance features such as nav¬ 
igation and in put/output. Server-side 
JavaScript statements are delimited by the 
<sener> and </server> Lags. 

Example 1 is a server-side script that 
prints the message *'helio world."" To print. 


use a built-in print function on the serv¬ 
er side to display values in an HTML for¬ 
mat. Tlie file ""helloJitmi” illustrates tlie 
use of the print hmetion. 

Next, compile Example 1 into a web 
file and install the program on the server. 
Use the command-line compiler to com¬ 
pile and generate a binary' file (a bytecode 
version of the script); for instance, kioomp 
-v-o hello.u^h hello.btml. 

Finally, use the Application Manager 
(included witli Netscape UveWire) to in¬ 
stall the web file so that it is identified by 
the server. Users can then access the ap¬ 
plication by providing the URL. The serv¬ 
er extension dynamically creates HTML 
code bascxl on the statement and sends 
the HTML to tlie client. 

Figure 1 illustrates the steps required 
for server-side JavaScript to process a re¬ 
quest from a client. 

Maititaining Client 
Information Across Pages 

JavaScript has an object framew'ork that 
allows for the addition of simple, persis¬ 
tent states tliar t^an be shared across pages, 
applications, and servers—extending the 
capabilities of web-based, client-server ap¬ 
plications. Tlie advantage is that 
users no longer need to keep track 
of preferences; die application reg¬ 
isters them. 

There are a number of concepts 
central to the JavaScript program¬ 
ming model: 

Objects. Objects are program con¬ 
structs that have properties and 
methods. Every object has a name. 
Software objects are modeled af¬ 
ter real-w orld objects in the sense 
that tiiey have a state and behav¬ 
ior. A database programmer can 
consider the result of a query as a 
query" object. Objects have rele¬ 
vance to the programmer’s appli¬ 
cation domain. 

Properties, Properties can be 
thought of as attributes tliat repre¬ 
sent the state of objects, such as 
weight, color, taste, and so on. 

(continued on page 16) 
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JAVASCRIPT 


(continued from page 13) 

Property values. Property values can he 
referred to using die syntax: ol^ectprope?- 
ty. For example j if the result of a database 
query Ls considered as an objea result and 
one of the attributes in die object identifies 
the number of reUimed rows as retunied- 
rows, you can access die value and use it 
for substitution into a page at a later time. 


Table 1: LimWire object framewod^. 


The value returned is always a string. It is 
also possible to assign values to properties. 
For example, resuU.retumedroies=4;. Equiv¬ 
alently, it is possible to assign the values as 
result[0]^4;- The ordering of the defined 
properties corresponds to die airay element 
order; see Figure 2. 

Methods. Methods are functions asso¬ 
ciated with an object. A function 


init_name(name) can be written to ini¬ 
tialize the name of the object associated 
with die name that is passed. A function 
definition consists of the function key¬ 
word, followed by the name of the func¬ 
tion, a list of arguments separated by com¬ 
mas and enclosed widiin parentheses, and 
fmally, the JavaScript statements enclosed 
in curly braces; see Example 2(a). To con¬ 
vert die function into a method, associate 
the function with an object, as in Exam¬ 
ple 2(b). A method can be invoked on an 
object; see Example 2Cc). Invoking a 
method is akin to sending a message to 
the object. 

UveWire Object Framework 

Netscape's LlveWire object framework pn> 
vides the prededned objects RtX}tiest Clmij 
Project, and 5t^;i!^for application develop¬ 
ment. ^Iiile some of diese objects contain 
predeRned data provided by UveWire, you 
retain the flexibility to define properties. 
Tliese properties maintain application data; 
for example, the object can hcjld the cus¬ 
tomer number or user ID and transport llicse 
items across pages. The key difference be¬ 
tween these oIijecLs is the lifetime during 
which tliey are acce.s.sible. Table 1 lists all 
the predellned ofijeas and some of tlie ac¬ 
cessible default properties. Note that 
UveWire objects can be accessed in func¬ 
tions by passing die alxwe objecLs as pa¬ 
rameters. 

Request objecis are created by the serv¬ 
er for each client request. When users 
click on the Submit button or request a 
URL, the uansaction is coasideied a request. 
Tlie raciest cjhject has tile shortest lifetime. 
I'he advantage of the request object is 
tiiat its properties are initialized witli some 
of the default properties and with pa¬ 
rameters such as fonn variables and URL- 
encoded variables. The properties of the 
request object can be referred to from 
tlie moment that tlie request object is cre¬ 
ated, After the server has finished re¬ 
sponding to the request, the request ob¬ 
ject is destroyed. 

Coasider an HTML form called 
'Pew.html,” whidi takes certain aitribiites 
about a defect frt)m the user as input; for 
example, the prioriw level of tile defect (ei¬ 
ther 1, 2, or 3)- The user dicks on the ap- 
proprLite level and then clicks the Submit 
liutton. The action pan of die fonii dictates 
the p;ige that will process tlie input. The 
name of each in[iut element in an flTML 
fonn corresponds to a request property, 
llie name of each request Ls die name of 
the held on the associated form. ^Iien us¬ 
ing CGI as a way to process die fomi ele¬ 
ment, you obtain the parameters from the 
URL (using the GET method or environ¬ 
ment vanahle QUERY_STR1NG), or from 
the standard input via die POST method. 


Object 

Type 

Default 

Property 

Methods 

Features 

Request 

agent 

ip 

protocol 
method (from 
Form Elements 
or URLs) 


Shortest lifetime. 

New request created for 
each cneni request. 

Destroyed when server 
has finished responding 
to request. 

Client 

No predefined 
property 

e xpi ration (seco nds) 
destroy {) 

All requests by the same 
client will share the 
same client object. 

Server creates new 
client object each time a 
new client accesses the 
application. 

Project 

No predefined 
property 

lock {) 
unlock 0 

Contains global data for 
the entire application. 

Project object is 
automatically destroyed 
when the application is 
stopped. 

Server 

agent 

protocol 

host 

port 

hostname 

lock 0 
unlock 0 

Contains global data for 
the entire server. 

Server object is 
destroyed when the 
server Is stopped. 



Database 

Engine 


User requests a page. 

Server Authorization takes 
place as defined in the 
configuration phase. 

Server creates a new request 
object and initiates its built-in 
properties. 

LiveWlre creates a new client 
object If It can't locate a 
preexisting object. 

LiveWlre saves client object 
properties immediately before 
outputting the page to the client. 
The mechanism used to store is 
dependent upon the technique 
selected at deployment time. 


6 


Output HTML page. For static pages, 
the server sends the HTML content. 

For dynamic pages, Live Wire performs 
application logic to create HTML and 
sends it to the client. 

7. At this time, LiveWlre destroys 
the client object or serves it, 
dependent on the expiration time set. 

If the destroy method is called, the 
client uses a built-in expiration mechanism, 
or the client exits the client’s software. 
Destroy the request object 
e-mailed In step 2. 

9. Server performs data login as 
configured at set-up time. 


8 


Figure 1: Steps required to ptocess a request from a client. 
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By using the request object^ it Ls possible 
to obtain the parameter values in a uni¬ 
form way. Assume that new.html contains 
Example 3(ti). The file insert .html can re¬ 
fer to user input in the priority field by us¬ 
ing request.^onty, see Example 3Cl:>i 
The default properties of the request 
object are 

• agent, the name and version informa¬ 
tion of the ciienfs software, 

• ip, a property that provides the IP ad¬ 
dress of the client. 

• method, the HTTP protcxiol methtxl as¬ 
sociated with the request (GET, POST, 
or HEAD). 

• protocol tJ'ie HTTP protocol level sup¬ 
ported by the ciienfs software. 

'Fhe request oh\e<l is automatically ini¬ 
tialized with the values for the default 
properties. 

It is possible to pass variables to 

the URL by appending a question mark. 
For example, in the issue-tracking tool ap¬ 
plication (to he discussed later), this facili¬ 
ty helps determine the sorting order for the 
defecLs (priority, issueid, status, and so on). 

The ordering is achieved by manually 
encoding request variables as follows: 
First, a question mark is appended, tJien 
the variable, equal sign, and the value. 
Multiple variables can be passed by sep¬ 
arating the variables using the sign. 
The variables that are encoded as a part 
of the URL appear as request properties, 
initialized with values that have been 
passed. 

For example, in the HTML file 
view.html, hyperlinks enable users to sort 
defects in the database. Tlie r^^tiest.choice 
value w'ill be ""bypriority" when the re¬ 
quest ob}ea Ls created for the URL request 
<A HREf ^ "view . h tm l?cho ice=hyprio ri- 
ty *^P?io?ity</A>. 

When an application is acc'essed by many 
clients, it is necessary to deal with each 
client individually, since the state of each 
client may be different. In a shopping-cart 
example, each client can have different sets 
of items stacked in a cart It is also neces¬ 
sary to maintain these client objects between 
transactions. The c±?jea framework provides 
a choice of different techniques to deploy 
an application, Tlie client object is alive for 
eacii subsequent request. Additionally, the 
client object c:an be explicitly destroyed. 

Often, multiple clients use a common 
pool of data. The project object provides 
a means to share an object among them. 
When a new application is started, a new 
project object is created. Correspondingly, 
when the application Ls stopped, the pro¬ 
ject object is destroyed. 

To ensure tliat multiple clients do not 
modify shared data at the same time, a lock¬ 


ing facility is provided. This locking provi¬ 
sion ensures that only one client may mod¬ 
ify a project object at a given time. Otlier 
clients must wait until the client releases 
the lock. Consider a projea involving tlie 
creation of a defea-tracking tool One of 
the tool’s subcomponents adds newly dis¬ 
covered defecLs. Each defect has iin ID by 
which it can be uniquely identified. When 
multiple clients try to log a new defect, it 
Ls first necessary to a.scertain diat each de¬ 
fect has a unique key, namely, the ID. 

Using a project object and locks, it is 
possible to ensure that only one client at 
a time can increment this ID. To obtain 
the last issueid in the database, the HTML 
file new.html makes use of a feature of 


server-side JavaSaipt called “cursors.'’ Set¬ 
ting the issueid in ascending order helps 
ensure that the lastld Ls the largest. The 
project object is locked, and incremented 
by 1. The property nmissideid of the client 
object Ls initialized to contain the new val¬ 
ue used wMe logging the new defect and 
issue. Example 4 illustrates the use of the 
project object. 

Server objects contain global data for 
the entire .server. Wlien multiple applica¬ 
tions must share information, the server 
is indispensibie. The server object pro¬ 
vides the following default properties: 

• agent, which provides the name and 

version of the serv^er .software. 
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must-have features: 
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Search Engine 
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and Authors 
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♦ Copy/Paste Functionality 
4 Export RIes 

4 Save Searches for Quick 
Access later 
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When you need the programming 
expertise that Dr Dobb's offers, there’s 
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CD-ROM into your drive, search for 
your topic of interest, and view your 
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something you want, print it, copy/paste 
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JAVASCRIPT 


* protocol, which refers to tlie HTTP pro 
tocol level. 

Server-Side Functions 

Server-side JavaScript provides functions 
for use in an application; some of these 
are used in the sample application in- 


Example 1: Typical sen^r-side script. 


eluded with this article. You c^an also cxe- 
aie your own functions in a separate file 
and include thorn with any applications 
to be deployed. Example 5(a) can be used 
to define a function, w^hile Example 5(b) 
can be used to find a maximum of three 
numbers and return the values. 


A detailed description of server^side 
JavaScript's .syntax and statement makeup 
is provided in the reference manuals for 
JavaScript. 

Managing Applications 

Netscape’s LiveWire comes with an 


<htinl> 

<hefld> <title> Print hello program </title> </head> 
<body> 

<server> print("hello world"): </Gerver> 

</bpdy> 

</html> 


(a) 

<F0RM METHOD="post" ACTION^"insert,html"> 

Priority: 

Cinput type^radio name-priority valiie=l checked>Levell 
Cinput type^radio name=priority value=2>Level2 
<input type-radio name^priorlty value-B>Level3 
<input type=submit value=lnsert> 

</mm> 

(b) 

<server> 

databaee.execute("insert into issue(priority) 
values ("+ request.priority 
</server> 


Example (u) The neiv.html file; (b) using imon btm! to 
refer to user input. 



Figure 3: An issue-tracking tool 


(a) 

function init^name(name) t 
this, name = name; 

} 

<b) 

Syntax: object.MethodName = FunctionName; 

cUEt. init_name - iiiit_naffie: 

(c) 

Syntax: objacl.M6thodName(arguments) 

oust. init „name (" cha r les"): 

Example 2: (a) Function definition; (h) comerting a 
function into a method; (c) inmking a method on an objecL 


<server> 

project*lock(): 

project.lastlssuelD = 0: 

/* using aggregate functions to get last issue id */ 
cursor - database*cursor("select ID from issue"); 
while(cursor * next()) 

[ 

project*laatIssueID = cursor.id; 

] 

cursor*close() ; 

project*lastIssueID - 1 + project.lastlsauelD; 
client .tiewisBUell} = project . lastlssuelD; 
project.unlock{); 

</Berver> 


Example 4: Using the project object . 


(a) function name (Iparam [.param,,*,,. J 1) ( 

//server side JavaScript statements 

] 

(b) function max(a ,b, c) [ 

var max = a; 
if (b > c ) { 

if (max < b) [ 
max = b; 

} 

else if (max < c) [ 
max = c: 

} 

return max; 

3 


Example 5-' fa) Defining a function; (h) finding the 
maximum of three niimhefs and returning the t^alue. 


cust[0] = "charfes*’ 
same as 

cusl.name = “foo" 

cust[l]=21 
or cUBt.age = 21 

cust[2] = 2134 
or cust.ssn = 2134 


Figure 2: Object properties. 


name 



age (properties) 


SS# 
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Application Manager that can be used to 
install your application using these steps: 

1. Complete the application using Java¬ 
Script embedded in HTML files. 

2. Use the command-line compiler or the 
Site Manager tool to compile the 
LiveWire applic'ation and link it on the 
server. A sin^e output binary file is pro¬ 
duced with a .web extension. 

3. lastall die application asing the Appli¬ 
cation Manager. If an existing applica¬ 
tion Ls nKxJified, it may be necessary to 
redstart it. Tlie Applic'ation Manager adds 
a URL prefix to reference tlie applica¬ 
tion, the path to the compiled binary 
file (.web), and the method used to 
maintain the client state. (You can also 
remove an application using the delete 
option.) 

LiveWire provides techniques to main¬ 
tain the client object on either the client 
or the server. The technique you use de- 
pcTids on the needs of the application and 
environment. Techniques to maintain die 
client object solely on the client include 
client cookies, and client URL encoding. 
Techniques to maintain die client objecl 
solely on the server include ipaddress, 
short cookies, and short URL encoding. 


Run the application by specifying the 
LIRL to access the server with the prefix 
(as determined during the installation pro¬ 
cess). Trace the applic'ation execxition by 
loading and appending die trace to the 
URL. 'fhe trace feature helps display the 
properties of the various objects. 

Example Application of 
Server-Side JavaScript 

Figure 3 shows the issue-tracking tool 
created using JavaScript. This tool was 
made with the built-in object framework 
and was designed to work with Informix- 
OnLine Dynamic Server. It is based on the 
Web Integrated Software Environment 
(WISE) project sponsored through a co¬ 
operative agreement between the NASA 
Software IV&V Facility in Fairmont, West 
Virginia, and the Concurrent Engineering 
Research Center (CERC) at West Virginia 
University. (For more information, see 
http://research.ivv.nasa.gov/projec'ts/WISE/ 
wi.se.html.) 

Usdng One (lisdngs begin on page 20) 
is the HTML file Kxil.html, which contaias 
the script required to open a conneaion 
to the database. The user is informed of 
any errors in connection. Netsc'ape Navi¬ 
gator suppoas frames, a tool that c'an be 
used to create multiple scTollable regions. 


Each region can be assigned an individu¬ 
al URL and can load information inde- 
p>endent of the other frames on the page. 
The main purpose of this file Ls to ciivide 
the web page into five frames, one each 
for action buttons, metrics buttons, the ti¬ 
de, viewing all issues, and a console win¬ 
dow to display error messages. 

Listing Two is view.html, which con¬ 
tains the JavaScript statements nece.ssary 
to print all defects and issues in the 
database. By default, the sorting of de¬ 
fects and issues is assumed to be by an 
ID (a unique numerical identifier). 

The client object has a property choice, 
which is inidalized by default to byid ft 
the requested object cbes not have a prop¬ 
erty choice defined. A database cursor is 
returned as a consequence of the SELECT 
statement. Different types of database ob¬ 
jects can be created depending upon the 
value of the client object’s choice proper¬ 
ty. A table of all defects and issues is print¬ 
ed with a header displaying the titles for 
each of the columns. The cursor is used 
to retrieve all rows in the database that 
satisfy the query. Once the answer set is 
printed, the cursor Ls closed. 

You should provide the flexibility to view 
defects and issues sorted in different or¬ 
ders: by choice, by status, by priority, and 
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• 7 of the most important books ever written on Graphics Programming 


n: 


I eed to get up to speed on 
graphics programming— 
fast? There’s only one defini¬ 
tive source you can turn to— 
Dr. Dobb’s Essential Books on 
Graphics Programming CD-ROM\ 

Get seven of the most-essential books on graphics 
programming, with full text, diagrams, graphics, and 
source code—all on one CD-ROM. From fundamental 
algorithms to the most complex techniques, this 


CD-ROM lets you find all the critical information 
you need for your graphics programming projects. 

Texture mapping, color modeling, and 
morphing—ail 
optimized for 
speedy 2-D and 
3-D graphics 
programming. 
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by category. Note the way that enccHded 
variables liave been added. When a user 
dicks on any hyperlinks, the requested ob¬ 
ject is created with a property choice dial 
is initialized by either byprionty, 

hycategory, or 

Listing Three (new.html) contains 
JavaScript statements that enable a client 
to add a new defect or issue to the 
database. A project object is used to up- 
date the unique ID among multiple 
clients. Since every defect and issue has 
a unique ID, it is necessary to ensure that 
each new" Lssue is also assigned a unique 
ID or key for general referencing pur¬ 
poses. A lock is put on the project ob¬ 
ject whenever a client logs a new issue; 
other clients must wait until a unique key 
is assigned for their defects, A few state¬ 
ments are added to iterate through the 
database and to find the largest ID used 
(in iliis article’s example, they're stored 
in ascending order). The ID is incre¬ 
mented and the clients’ neunssueid prop¬ 
erties are initialized. 

In most cases, it is useful to have met¬ 
rics associated with an Issue- or defect¬ 
tracking tool. Metiics help clients view^ die 
numlier of defecLs yet to Ix! resolved, pro¬ 
viding an idea of the process stale. List¬ 
ing Lour (ovc.htrnD queries the cLitabase 


for the number of open and closed issues 
and prints the output. The file contains 
two SELECT statements, wliich define two 
cursors. Iteration is through the cursor, 
Tlie variables open and closed keep track 
of the numlier of open and closed issues. 
The print funaion is used to print output 
in HTML fomiat, 

The new html file (Listing Five) uses 
HTML to provide a M-in form in which the 
user can enter data relevant to a particular 
defect. This file contains all the statements 
required to service the request from the 
form in new.html. Wlien a user clicks the 
Submit button to submit a new Lssue, a new 
object is created and all named el¬ 
ements of the form are transformed to the 
request object's properties. Tlie issue is in¬ 
serted using tfie database.execute statement. 

When cHenLs view an issue, a hyperlink 
reference is provided (as an action hut- 
ton) to remove the issue (see remove, html, 
LLsting Six), This delete feature can be re¬ 
stricted to authorized users only. The en¬ 
coded variables of this hyperlink contain 
the issue ID, A object property is 

used to selectively remove tlie issue from 
tlie database. Once the defea and issue 
are deleted, control is redirected to the 
view .html page. Listing Seven (tide,html) 
initializes tlie title of the application. 


Listing Eight (action.html) targets the 
appropriate Ifame, whidi wdl display an 
HTML file. This file contains the necessary 
action buttons to view, enter a new issue, 
or provide online help, 

Listing Nine (detail,html) prints the de¬ 
tail pertaining to each issue in HTML for¬ 
mat, Wlien view.html processes a request 
and displays the defects in the database, 
each issue's ID is displayed as a hyper¬ 
link. The hyperlink in view.html that is 
associated with each issue’s ID has en¬ 
coded variables that indicate the issue/ 
defect ID. Thus, when users click on the 
link, the request object’s id property is 
initialized to its uniqueid, as stored in 
the database. The uniqueid is used to 
reference the issue selected by the client. 
Using the requestid, Listing Nine contains 
statements diat declare a cursor; that cur- 
.sor then returns an answer set with a 
matching ID. Subsequently, details of the 
issue are printed. 

Finally, Listing Ten is used to compile 
all ilTML files containing JavaScript state¬ 
ments into bytecode. This program must 
be installed using the LiveWire Applica¬ 
tion Manager. 


DDJ 


Listing One 

<IIEAr3> 

<TnLE> DeBonatratlDiv ef J-avsSrrlpt Server S'lde Peaturec/TITLED 
</HEAD> 

<BOD(T> 

<[ try ta iqontiect to JnfprBiiK CJriline 7.1 > 

<.Etrver> 

/* 'Trying to connect to test dfltabaee 
if(I database,connected()] 

{ 

database,connect("IHFORHTX'*, ''Eumap-az.ollsh*", "toet''): 

} 

/* Print ercor isessage */ 
if (J dat obasB. cotinEOted ([)) 

t 

print I "Error; CJitable to counBct tp database^")? 

} 

</BErver> 

< I create the screen dump for showing the lasuea lising f ranes^ 
(FEAMESET RQWS="10/\757.IS/"? 

<lil oli{in=eeiiter><blinl£>FraiHe ALERTEDAi],inJt></lil-> 

<p!^ 

This ddCUdieot ia deaigned to be vieved lieing <b>Metscape 
Prone features. If you are eoeing this messaga, you are uaing 
B frame {i'>challengedbrowser. 

</p> 

<p> 

A fb>Fra»e-capHble<7b> browser can be gotten ftcoii 
<a h£e:f=http,^//haide. netscape .iCam/^HetacBpe 
CoiTimunications</a>. 

</p> 

</»0FRAMESi 

< E BEBign a reginii for the title vindpu > 

<FRAME SRC=^"title,html" NAME=title MARGIMWrDTa=5 
MAIIG1HHEIGHT=5 SCRDLL1WG=M(1> 

<E assign a region for displaying action buttons 7 
<FRAM]1SET GOLS=''257.75/"> 

<FRAME SRC^"action.html" NAME=aotion MARGINWIDTH=5 E1ARGIHHEIGHT=5 
SCROLL rNG^E70> 

assign a region for displaying tha isaues in the databaao^ 

<FRAME SRC^"view.html'* lWIE=''view'^ HARCrMWTI>TB="5-' 
MARGrNHEIGHT=''5" SCROLLING^ "YES" > 

</FRAMESET> 

<FRAMESET COLS="70/,30/"7 

< I region tp hold artinn buttons for metrics^' 

<FRAME SRC^"metrics.html" NAHE=mfitrics SCR0LLING=M07 
<laaeign region for error meBsage di 0 play> 

<FRAME SRC-"console.html" NAHEcconsole SGE0LLING=H0^ 

</FRAMESET') 

</FRAMESET! 

^/BODY> 

</BraL> 


Listing Two 

<htBil> 

<head> 

Gustoner Database </title> 

</head> 

<body> 

<Eerver> 

/*te3t to see if the choice property ie defined */ 
ift toqueat.choice 1= null) 

f 

client..eboite ^ r&queat.rhoiceE 

] 

elEe 

t 

/^make byid the default ordering rhoica for viewing iaeueE */ 
cllent,choice = "hyld”; 

3 

/•^create datebace object based on the ordering requested*/ 
if tcllent.choice “= "hyid"'Jt 

cursor = dat&beee.cursor (’'select • from issue order by ID"3; 

3 

else 

if (cliEat, choice "hyatatue'‘H 

cursor = databese.cursor("select • from issue order by status"}: 

3 

else if (client.choice — "bypriority"K 

cutfior = database.GHitBor("select • ftcTO issue order by ptiocity"): 

1 

else If (client,choice = "hycategory"){ 

cursor - database.curBor("Bel«ct * from issue order by category"): 

) 

(/server! 

etcreate table headerB With URLs that have □rder choice encoded) 
(TABLE BORDER! 

<TR! 

<TD><A t3REF=’'view.html?cboice=byid"!lflaue Mot/A!(/'n>! 

(TO C0LSPAM=4 > <A HREF^"vieii, bHll" )Abstract < /A) < /TD ) 

(TD!(A HREF*"viBw.html7choice=byetatua">£tatus</A) </TD> 

(TTl'!(A HREF=’'view,htlEl?[iboicB-hyprlority"!Friority(/A></TD> 

(TT>!<A 

HREF= "view, html ? choice^bycatega cy" !Catego ry< /A> ( /W> 

</TR> 

(literate thtougb ettrsor and print individual records! 

(server! 

whiletcurSa-r.neprtt)) C 
(/server! 

<tr! 

<td> <a 

href"detail .html? ID="+c,ursDr, id' !<soFver!print(cursor. id) ^ 
(/server)</a!</td> 

<td colspan-4) <Eerver!print(curBor.aiHBm3ry):</Berver!</td! 

(td! (aerv«r>prin.t(curaO'r.fltatug) :(/aerver!(/tdJ 
(td) (servftDpriiitfcuraor.pcloEityJ :</aervat></td) 
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<td> <Mrv#c> print < eurasc. eat aiary); < /flecver> < /td > 

</tr> 

<flexvejr> 

} 

/*cXaS^ the utlrecir ♦/ 
cursor.cIaaeO j 
</server> 

</tabled 
</BODY> 

</html> 

Listing Three 

<btmlJ 

<head> 

<title> Creating n«v iisue 
</head> 

<body> 

<server^ 

/•obtain loch on th# project object*/ 
projfcct.lockC)! 
proJoct-lastlsaiifilD = 0: 

/• uaiuft aggregate ftmctlone to last Isauo id */ 
etitfioc == database, cursor (^select ID from issue"}; 
wbile {Cursor n^nejct ()) 
t 

project.lastissueID = cursor.id; 

J 

cursor.close(j: 

/*get unique id */ 

proJect.laatIflsuelD "it projeet.lastlsfliiein-s 
client.nswiBsuelD ■ project.lastlastieID: 

/treleaae lock*/ 
project.unlock(3: 

</server> 

(Icreate an input entry fom for logging a new isEue> 

Cbl> NEW <Beryer> print [project, lastlssui ID}; 

(/server^ </hl> 

CfORK MBTH00=^*poBt^' ACTION-" insert rhtml"> 

Ctable cellspacinE=2 ]Mrgiii=3 border> 

Ctt>ttd>IsBueID:<7td><td> 

<8«rver>print{project.lastIssuelD)</servar ></td> 

</tr> 

i^input typfl="hiddeii’’ name^^ID" valtifl=’project. lafitlBsuelEf' 
sire»"4"?«tit> 

<tr> 

<td>Category</td> <tdJ 

< Select IiHliie-" category" > 

<optioii> error <apti 0 n> change request <option> unclassified 
</select> </td> 

</tr> 

Ctr> 

<td> Priority </td> <td> 

< input type=radlo naine»priority value^l chetited>Levell 
<input typ#=radio naiie«priorlty value=2>ievell 
<input typ*«radlo naine=priorlty value=^3>lieveii 

<tr> 

Ctd>Abstract;</td> 

<td> itaatarea rows=4 cola=S0 nEBe=snoary></tertarea^</td^ 
</td? 

<tr> 

<td> Statue: t/td><td>Open c/td> 

<input type="hidi3eii" na»e="BtatuB"‘ value'open ><br> 

(/tri 

</table> 

<input type="subnit" value®"eul»lt lsflue1"> 

<input type®"reset” value®"E.eaet”> 

</FOKfl> 

</BODY? 

</BTKL> 

Listing Four 

<btBa> 

chead> 

Ctitle> CuBtoBfiE Database </titled 
</head> 

<body> 

<server> 

/•query for nuaber of open issues*/ 
var open = 0. closed ®0: 

cursor ® database.cursor{"select * fro* liUUe i wbere 
i. status “ '"open^")! 
while(cursor.neat{}j 
E 

open = open +lj 
1 

cursor.cloBet). 

/•query for nunber of closed issues*/ 

cursor = database.cursor{"select • froa Issue 1 where 

i.status - ^elose^"): 

while{cursor.next (}) 

£ 

closed “ closed +1; 

3 

cursor .closed; 

print {<hl > CURRENT STATE i </hl > ") J 
print{”Cht># of open isBues;"}: 
print{ppenj; 

print{“thr>ll- of closed issues:"); 
print{closed}; 

</8erver> 

</BODY> 

</HniL> 


Listing Five 

(htmlJ 

<head^ 

<tltle> CuBtoter Added </titled 
c/head? 

(body> 

<Berver> 


/•insert the issue into database using tbe request object^/ 

database.execute("insert Into 

iBsue CId.summary.priority .status^category} value 

a (" + 

request.ID * + 

request, smaaary + + 

request, priority + V** + 

request.BtatUB + + 

request.category + 

/• 

database-execute {*'inBert into is sue [id} values {” + 
request.ID + "}"): 

•/ 

redirect {"view, html"); 

</server> 

</body> 

</html> 

listing Six 

<htiil> 

<bead> 

<tltle> Issue Renoved </title> 

</hesd> 

<body> 

<servers 

/•delete issue fro* database*/ 
if (request.ID 1= nuU) 

database.execute("delete fro« ieeue where leBuenid - " + raquest.ID) 

redirect ("view* htjnl"): 

</BerVer> 

</body> 

^/btml> 

Listing Seven 

<HTML> 

<B0DY lACKGROUMD® "http: /iaages / gray.roek * gif” 

TUinV TFOETi" i VTTTVPVIT” 

KiDY LINE="*RFFFM" VLUK^-OTFUE" AUMtt="FFi<f00"> 

(PflEV 

CH2)^ CIJIG ALia«=^iddle tflDTH^125 TiElCHT=20 
SE{>"http; / Images/inf ormix. gif” > 

Issue fracking Tool </ii2> [For beano Purpose) DemonstratioD of JavaSoript 
Server side feature. January 199b. sudhaiginforttlx.co[ffi </PEE> 

(/BODTO 

</HTML> 

Listing Eight 

<h™l> 

<B0DY EACKCROlFNt^"http: /iMgee/chalk.jpg"i 
<h3> ACTION BtlTTOHS <m> 

<P> 

CJHO AlI(5H=MIIl'DLE JRC="http;/iBagfls/i!;oBbullet.glf"><A 
3IRFF="Tiev.}irtinl" 

TARGEr='Viaw” >New IsBue</A> 

<P> 

<jm ALI{a=MrDDLE SRJ>"http;/l*ages/toeibulIet.|if"> 

<A EREF»"help.html" !CASiGEr=‘'view''?HElp</A> <P> 

CP> 

<IMG ALIGN=MirinLE SRC="Iittp;/ijnagee/to!fflbuUet. gif"> 

<A HREF^"view.htiil" TAtUjET="view" >Show List</A> <P> 

</BO(D(Y> 

</|!m> 

Listing Nine 

<btBl> 

<head> 

<title? Issue Details </title? 

</head? 

<bady> 

<SErver> 

/•get details of issue matching requastlD property of request object*/ 
if{peqiie&t,ID f= null) 

r 

client*iBd = request.ID; 

cursor ® database.cursor["select * ftoni isaue r where r.id = " + request.ID); 

whlle{cursor.next(}) ( 

</Bervet> 

<1 print the respective fields of the issue? 

<hl>ISSUE NO: <aervier> print [cursor * id) </6erver ></hI> 
stable border? 

<tr> <td>AbfltrBct^/td?<td? 

<aerver>priiit{cuPBor. Bumary) ^/server? </td></tr> 

<tr> <td> Status (/tdXtd? 

<server Sprint {cursor. statusX/server? </td></tr? 

<tr> ttd?Priority</td><td? 

<aerver?print(cursor.priority)</aerver> </td?</tr> 

< tr > <td ?Category</td? <td? 

Cserver? print (cursor. category) </aerver? </tdX/tr? 

</table? 

(server? 

} 

curaor.closeO; 

(/server? 

<hr? 

(IMS SfiC=”http:/imflgas/redbell. gif''? 

<A HRlf remove.html?lD="+client.isd"'>Delete this issue</a? 

(/body? 

</html? 

Listing Ten 

. ./. ./hin/ltfcomp -v *o tool.web tool.hrtml uew.html 
insert*htKl viEw.html remove 
.hml detail.html ovc.html 

End listings 
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Comse on C/C'f'f 





j 1 Stevens, a world renowned programming expert 

_ j and contributing editor for Dn Dobh's Journal^ 

^ has created the CD-ROM to answer all your 
C/C’’"*' programming questions ” the Ai Stevens Cram 
Course on C/C^^. 


This CD-ROM includes the complete text of three books 
written by Al Stevens, an interactive step-by-step tutorial 
with precise explanations, video clips of Al discussing 
important topieSj a compiler directly connected to the 
exercises, lots of usable source code, plus a memory feature 
that bookmarks your place for quick returns to prior sessions. 

Use this CD-ROM on your programming projects to 
answer questions, work through actual examples, compile 
your example source code, and make sure it's correct 
right then and there. 


Or complete the form and return to : 

Fax: 913-841-2624; E-mail: orders®mfi.com; 
Int’l: Use mail, fax, e-mail, or call 913-841-1631 


Please send me an Al Sfevens Cram Course on C/C++ CD-ROM 
today I My price is $69.95 (plus $2.00 U.S./Canada; all other countries 
$10.00). Please add safes tax in the following states: CA (8.5%); 

GA (6%); IL (6.25%), KS (6.9%). NY (B.25%), TX (8.25%) 
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□ Chedc 
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n 

□ Amex 
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Exp. Data 



No matter what your level of programming expertise, the 
A/ Stevens Cram Course on C/C^^ will help you become a 
more proficient program men 

This multimedia CD-ROM features: 

■ Three Complete Programming Books 

• Interactive Tutorials 

• Built in Compiler 

• Video Clips 

• Bookmark for Quick Returns 

• Background Music Performed by Al Stevens 

See screen shots and a more detailed explanation on our 
Website: www.ddj.com/cdrom/alstevens.htm 




Welcome to Prograrrunmg 

Straightforward explanations of 
computer fksi code^ and language 
makes programming simple. 



Al Stevens Teaches C 

The perfect introduction to C with 
an organized, structured approach, 
teaching good programming through 
good example. 



Teach Yourself... 

This hook demonstrates the hows and 
whys of C-^-^ program design in an 
accessible, informative style. 


L ■ B n A tr 



Order Today! 800-548-1971 
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‘ 4S6/40 (486^66 rcciDmmended) 
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- CD-ROM 

- Mouse 

• 8 MB RAM 


- Wm95orNT 
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* 5 MB Disk Space 

(Will run on Windows 3-1, bur requires 
manual installation) 
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COMBINING ENVIRONMENTS 


Combining Visual 
Development Environments 


R ogue Wave’s JFactoiy and Syman¬ 
tec’s Cafe are visual tods for Java- 
based devebpmenl. Fundammtal- 
ly, Cafe 1.20 is a fast compiler with 
a graphical debugger, a class 
browser, an editor dial liighlights Java syn¬ 
tax, a screen painter, and a code genera¬ 
tor. It is an open environment, so you can 
add menu items to the Tools popup to 
spawn stand-alone applications such as 
Netsc^apx? Navigator or a calc\ilator. Cafe or¬ 
ganizes these tools in a tabbed desktop, al- 
bwing you to set up one desktop config¬ 
uration for editing, another for debugging, 
and another for browsing. A tab control 
allows swapping between desktops, and 
you can easily add new tabs for new con¬ 
figurations. 

JFactory 1.1, on the other hand, is pri¬ 
marily an application designer and code 
generator. It includes JWidgets—a col¬ 
lection of packages that augments the 
JDK with toolbars, image buttons, ani¬ 
mation, and a table objecn. In addition to 
the WYSIWYG screen-painting fa¬ 
cilities, JFactory includes an option 
that allows programmers to run pro¬ 
totypes— not just individual screeas 
but entire interfaces—before com¬ 
piling. JFactory is also an open en¬ 
vironment. After code generation, it 
can spawn a command-line com¬ 
piler, debugger, and applet viewer. 

It also allows you to add tools like 
Navigator to its menu structure. 

Theoretically, JFactory and Cafe are 
complete solutions to visual Java de¬ 
velopment, but they have different 
.strengths. In developing the JavaTax 
project I present here (available elec- 


Ellis is a freelance writer in Atlanta, 
GA. He encourages everyone to pick 
up a copy of his new World Warily 
novel, Bbw Happy, Blovv' Sad (Com- 
fnonwealth Publications, 1996, ISBN 
1-55197-321-9). He can he contacted 
through the DDJ editorial offices. 


JFactory and Cafe 
mix it up 


Wm. Ellis Oglesby 


ironically; see “Programmer’s Services,” page 
3), 1 us<xl the best features of each. In the 
process, I learned the hazards and rewards 
of mixing and matching tliird-party tods. 

JavaTax 

Tax-preparation software is ideally suited 
for a web-based applet. Online tax-return 
filing is yesterday’s news, so online prepa¬ 
ration must be the next logical step. Tax¬ 
payers generally only file once a year, so 
it makes sense to rent the software for 
one-time use. HTML Ls the perfect medi¬ 
um to navigate the tomes of IRS regula¬ 
tions and requirements, but return prepa¬ 


ration requires calculation. Users could 
print a copy for their records and e-mail 
the other to Uncle Sam. Finally, the emer¬ 
gence of electronic signatures and online 
banking could provide the technological 
infrastructure and safeguards needed to 
make online tax preparation a reality. 

JavaTax takes users step-by-step through 
the U.S. Form 1040 via a series of “wizard" 
dialogs, accepting tax data and automati¬ 
cally calcnjlaiing subtotals and totals. When 
tlie 1040 requires data from other forms or 
schedules, such as my personal favorite. 
Schedule C—Profit or Lass from Business, 
JavaTax offers a button that pops up the 
appropriate form. When complete, the 
schedule data is automatically transferred 
to the 1040. Users cran navigate back and 
forth tlirough the screens, massaging the 
numbers until they reach an acceptable 
bottom line. Finally, a print option simu¬ 
lates printing the tax reaim and a submit 
button pops up an animation of a shrink¬ 
ing dollar sign that simulates sending the 
data back to die server. A commer¬ 
cial version of JavaTax would require 
implementing these features, but that 
is beyond the scope of this article. 

Making Tools Work Together 

In theory. Cafe and JFactory fit to¬ 
gether well. Prototype the front end 
with JFactory. When that’s done, gen¬ 
erate the code and load it into a (Zafe 
project. Use Cafe’s integratcxl editor, 
class browser, compiler, and debug¬ 
ger to add data structures and calcu¬ 
lation functioas. Voila! A finished ap¬ 
plication. 

Unfortunately, I don’t write appli¬ 
cations like that, and Fm not sure any¬ 
one else does, either. Even late in the 
devebpmenl cycle, I find myself in 
the Designer, resizing text fields or 
correcting .spelling mistakes in dialog 
captioas. Tills blurs the line between 
prototyping and developing, making 
tool integration more error prone. 
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COMBINING ENVIRONMENTS 


When integrating tools for projects such 
as JavaTax, the first task is to set up the 
desktop. After adding JFactory to Cafe's 
menu ter, I create a new workspace tab for 
designing. It contains only two Cafe tools; 
the class browser and the project manager. 
Fortunately, Cafe does not frame its tools 
within the application window (MDI 
style). The “empty'' space on the display 
is available for JFaaory components, sudi 
as Projea Manager, Object Manager, and 
Designer. Figure 1 shows this arrangement 
in action. 

JFactory's Project Manager (Figure 2) 
organizes all interface objects in a hier¬ 
archy. Applications contain windows and 
dialogs, Windows contain menus, tool¬ 
bars, and controls. Menus contain menu 
items. Toolbars contain tool items and 
controls, and so on. Creating a new pro¬ 
ject adds one window (an applet frame) 
to the project manager. Users can add 
new objects by right-clicking on object 
containers. 

Every interface object has a set of prop¬ 
erties (such as location or color) and a set 
of events to which it can respond (got- 
foa4s, lostFocm, cHcked, and the like), 
Tliese are listed in JFactory's Object Man¬ 
ager (Figure 3). A programmer can mod¬ 
ify these properties at any time. 

Doubie-clicking on a w indow or dialog 
in tile project manager opens that objea in 
JFaaory’s visual designer— a ik^ating can¬ 
vas wiili a tool palette for drag-and-drop 
construction of window^s and dialogs. It lias 
all tlie sizing, spacing, and alignment fea¬ 
tures expected in a WYSI^'G screen 
]>ainter. In addition to the standard Java 
componenLs (text areas, choices, buttons, 
and .so on), JFactory's tod palette supports 


JWidgets, and JavaTax takes advantage of 
these hi^y graphical features. 

Building the Applet Interface 

Since the JDK 1.03 does not support menu- 
bars in applet frames, JavaTax (Figure 4) is 
driven by a todbar with tliree tool buttons; 
one to fill out the rearm, one to print it, and 
one to subtnit it. Dragging, dropping, and 
aligning these components in the designei- 
is a 60“Second task. In tlie Objeci Manag¬ 
er, I specify how the components respond 
to mouse clicks. Choices include calling an 
external object, linking to source code, and 
popping up windows and dialogs. 

The tax return itself, as everyone knows, 
is an interminable series of lines, each con¬ 
sisting of a line number, some explanatory 
text, and a blank to enter tire data, Form 1040 
groups these lines into sectioas for Income, 
Tax Credits, Payments, and other cathodes. 
JavaTax reproduces tliis fomi with a series 
of wizard-like dialogs. Labels hdd tlie line 
numbers and explanatory text, md text fields 
provide a mechanism for data entry. 

Graphical buttons on the Ixjttom of tlie 
diabg allow users to cancel the task or nav¬ 
igate tlirough the form. In total, JavaTax 
ases eight graphiad buttons: five duilog but¬ 
tons (Okay, Cancel, Prev, Next, and Finish) 
and three toolbar buttons (Process, Submit, 
and Piint). The bitmuip asscxiated with each 
of tliese miLst contain images for six pas.si- 
ble button states: off, off disabled, off de- 
piiessed, on depressed, on, and on disabled. 
Becau.se JavaTax uses single-state buttons, 
only tliree sloLs are actually LLSed. Creating 
these six-sbi iniiigcs Is one of tlie most tinx"- 
consLiming steps in the entire [irojea. 

Altiiough the cotitent of tlie wizard pages 
is varied, die layout is essentially the same. 


Instead of creating each dialog individ¬ 
ually, 1 design a generic page with ten 
labels, ten text fields, and three buttons; 
and I store it in JFactory’s Object Gallery. 
This is a holding tank for reusable ap¬ 
plications, windows, dialogs, and menus. 
A large firm might use this feature to 
maintain company-standard screens like 
logon dialogs and About boxes— situa¬ 
tions where multiple applications use the 
same compound objects — but it's also 
an easy w^ay to store templates. Now, 



Figure 2: JFactory 's Project Manager. 
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Figure 1: JFactory and Cafe in a combined tcorkspace. 


Figure 3-' JFactoty's Object Manager. 
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wlien I create a new dialog, I can chcx>se 
from JPaaorv'^s prepackaged diabgs (bbmk, 
Alx>iit and standard), or select my ckvti wiz¬ 
ard. From the template, I create nine wiz¬ 
ard pages and modif^^ their properties in the 
Objea Manager. Though some dialogs re¬ 
quire otJier components, aich as group box¬ 
es, radio buttons, and button links to otli- 
er forms, the Object Gallery cuLs the 
interface development time in half. 

When the interface is complete. I can 
test it to make sure it behaves as expect¬ 
ed. Altliougli I have not yet compiled it, 
it looks just like iFs running in die applet 
viewen It proves I’m on the right track be¬ 
fore I begin adding back-end code. 

Generating, Compiling, and Running 

After achieving the desired interface, JFac- 
tory generates the corresponding Java 
source code. You have tlie option of gen¬ 
erating a .java file for each object or one 
large file. Like any other applictition gen¬ 
erator, tfie code is longer than w hat an ex¬ 
perienced programmer would write, but it 
is well commented and easy to follow. Mast 
importantly, it works. 1 could only find 
one situation that makes JFactory generate 
compiler-choking code— defining the ap¬ 
plet frame to be an empt>^ dialog— but this 
doesn't seem like a practical problem. 


JFaaory provides the option of com¬ 
piling the files with javac and starting the 
applet view'er For what it's worth, it works 
just fine, but 1 haven^t used command-line 
tools since Reaganomics. Instead, I sim¬ 
ply click on Cafe's Browse workspace tab, 
JFactory disappears, obscured by Cafe's 
project manager, class browser, and hier¬ 
archy editor. 

Adding Custom Code 

There are three tasks to accomplisfi pn> 
gramaticaily in Cafe: 

• Create a tax-data object to calculate and 
store tax data. 

• Write functions to read/write data to/ 
from the tax-data object. 

• Capture the Enter key to process data 
and navigate among text fields. 

Cafe's Project Manager organizes the 
files that comprise an application. Since 
JFactory does not automatically gener¬ 
ate the project, you must create a new 
one, add the generated source files, and 
point Cafe to Rogue 
Wave's JWidget pack¬ 
age. Once the project 
is correctly defined, 
the application com¬ 


piles and executes without any problem. 
If I liave bugs dawn tlie nxid, I can't blame 
diem on tlie tools (I can blame tliem on 
the JDK). 

Using the Class Browser 

I prefer to do all my work in Cafe's 
l>rowser. lake tlie editor, it highlights Java 
syntax. The top-left panel lists the ap¬ 
plet classes either alphabetically or in 
their creation order. The top right shows 
the methods and data members of the 
selected class, and the bottom half dis¬ 
plays the corresponding source code. 
Because Cafe's parser is independent of 
die compiler, it is not necessary to re¬ 
compile to update the browser. This tool 


public 

void initO { 

applet = thisr 
// zpb.begin Appletlnit 
pTaacData = nev tasData [); 
// zpb_ead 


Example 2: 

object. 


Imtantiating a taxData 



Jthv Sna^. 


Welcome to JavaTax 

Click on the toolbar to begin 




Figure 4: The JavaTax applet. 
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public 

class taxapp extends Applet [ 

private static Applet applet: 

// Initial jsi£a ■ in logical unita 

DinieTiEion initial Si ^e = new Dinieneior] (158. 64); 

// zpb.begid MainUsecVats 

/i zpb.end 

public 

void init O C 

applet = this: 

// Appletinit 

// zpb_end 

setlaakgroimd (Color. li^tSray) \ 
setFont(new Font(“Helvetica^, Font.PLAlH. 12)); 
LogF^intLaytJut IfLayout = new LogFontLayoutCtbis): 
eetLayout{lfLayotit); 

/ / zpb_begiTf MainAppletUsarHethcds 
/ / z:pb_etid 

1 

ii spb_ b agin UserClass as 
/ i zpb_enti 


Figure 5: Cafe's Hierarchy Editor 


// spb-begin IpcZDialogUserlfethods 
void Savelita()C 

i^TaiiUata. rental = 

(Ititeger. valueOf (pRantalEdit. getTeit [))) * intValue f): 
n^axData. farm = 

(luteger.valueOf (plarmBdit. getJextC))) -iutValue C): 
tiyraEDflta .tinea^layiflait " 

(Integer. valueOf f pUneiroloyeieiitEd it. getTejct 0)), intValue (}; 
n^azilata.SSBetiefita - 

(Integer .valueOf{pS&cialSecurityEdit , getTsKt 0)). intValueO; 
[jq/TaxData.otherIncQnje = 

(Ihtegar. valueOf (pOtherlncomfiEdit. getTaxt 0)). intValue () ; 

} 

Void updateEdits[j { 

pHeaitalEdit. setTart (String. valueOf (n^axOate . reutal)); 
pFaniiSdlt:. fiatTaHt (String. valueOf {nyTaxData. farm)); 
pOneffiployinentEdit.fletTeict [String. valueOfCrayTajcData.unenpioynjent)); 
pSociklSecurityEdit. aetTest (String. valuqOf (nyTasData . SBBqmef it a )) ; 
pnrbe rTnr cmaFjHit. serTpxr (String. valuaQf (n^aicData. DtberlncaiBe)): 
pTotal iTiccwp^it. setTe^rt (String . valueOf (in^aHiats. tcrtal InccuDe)): 

) 

// zpb.end 


Example 1: Main applet class generated by JFactory. 
Dr Dohh^s Sourcebook, l^ovembeHDecember 1996 
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pubMn hfflidleE<^ent(Evmt ej [ 

// i^bJsegiJi Inca)ialQE,Hflridl^'retit 

■ if <e,target instanceof Text^ield 

■ e.id ^ Eveut.KE^JPRESS. 

- . e.ke^r — 10-) ( 

adveDataO ; 

m^flMJata.calcuiateiO; 

. p^lcrt^IncojHeEdit, eet^ 

jC^tTing. valueOf (ii5?Ta2!i3ata. totallnccme)): 
■ ((Goiiparient] (e, targ?t)'), oertFcxiiia () r 

■ y/ Kpb_end 


Example 4: Checking for the Enter key. 

gives a good class-oriented overview of 
tlie application. 

The only problem with using Cafe and 
JTactory together is trying to add meml:>er 
data and metltods via tlie hrcwser in such 
a way that TFactory doesn't overwrite them 
when it regenerates tlie code. 

JFactory preserves user code by placing 
protect blocks at locations throughout tlie 
source. When it regenenttes the applica¬ 
tion, it simply copies the cx^ntents of these 
blcx:ks into the uixJated file. It is a llaw'le.s.s 
system, as long as the progjaninier dcxfsn't 
make changes outside of tlaese safe zones. 
Protect blocks occur often, so this shouldn't 
be an inconvenience. Fcjr example, I lello 
Work! has 14 of Lliem. 

Example I is an excerpt from the main 
applet class definition as generated by 
I Factory, The protect blocks are marked 
by tlie comments 2 ph_hegin and zf}b_en€l. 

Of course, Cafe isn’t aware of these 
protect blocks, and it has its own ideas 
about where to place code. Wlien 1 use 
tlie brow^.ser to add member data or metli- 
ods, they appear at the top of the class, 
and user classes are declared at the lx)t- 
tcm of the file unless a new source file 
is specified. If the code remains in these 
places, JFaaory erases it w'hen it regen¬ 
erates the application. 

Simple w^orkarounds include using the 
editor to define new^ meniliers within pro¬ 
tect blocks and flesh them out in the 
browser, or cutting and pasting into pro¬ 
tect blocks. Either way, Cafe’s browser 
finds them just fine. 

Data Storage 

JavaTax uses a custom data class, taxData, 
to store and calculate its dtita. Tills keeps 
all the information in a central location, 
and simplifies calculations involving data 
from multiple dialogs. 

1 created the new class witli Cafe’s Hier¬ 
archy Editor (Figure 5). Ifs basically an 
interactive class diagram that can manip¬ 
ulate an application’s inheritance struc¬ 
ture. By default, the Hierarchy Editor 
places new' base classes in their own file. 
Because JFactory is not aware of tliis file. 


It is completely safe to regenerate code. 
In addition to a default constructor, the 
taxData class contains variables to hold 
the application’s data and a cakulatet) 
function that computes all subtotals and 
totals at once. This easures the data is al¬ 
ways current. When the application is ini¬ 
tialized, 1 instantiate the taxData class by 
adding a line to the appropriate protect 
block, as in Example 2. 

Each dialog class has a protect block 
for “user variables" where I've added the 
entry taxiJata myTaxData^taxapppTax- 
Data, which allow'S each dialog to ma¬ 
nipulate tlie tax-data objeci directly. 

Managing the Text Fields 

Java handles data entry into its fields, hut 
you are respoasibie for w'riting that infor¬ 
mation to and from die application's vari¬ 
ables. JavaTax does this on a dialog-by¬ 
dialog basis. Each one has a sat^DtUaf) 
function that takes the strings in its text 
fiekLs, conveits them to integeni, and stores 
tliem in the cbta objea, updateEditst} does 
tlie reverse. Example 3 shows how' these 
two metliods are implemented. 

Colling the Functions 

I call myTaxDuta.calcuIaiei) and up- 
dateEdiisf } in the dialog's c onstructor af¬ 
ter the components are created and be¬ 
fore the window is show'ti. Tills ensures 
all data is displayed correctly. 

The dialcjgs must save their data w hen 
die user navigates from one page to an¬ 
other JFactory already genentted the ac¬ 
tion method ihai processes the Free and 
Next buttons; I just add a call to save- 
Data(} to diat method. 

So far, Java'fax displays each diak)g cor¬ 
rectly and saves die data wlien the user is 
done. FIowevcT, 1 also w ant it to update 
tlic calculated fields as the user enters data. 
1 accompEsh tills by mqiping the Enter key. 

JFactoiy’ generates a bandleEventf) 
function for each ivindow', and 1 extend 
it to check for key presses. If the user 
presses the Enter key while in a text field, 
I save the diiia, calculate and upcJbire tlie 
subtotals in the dialog, and place fcx:u.s in 
the next component. Example 4 .shows 
die necessary changes. 

'fhe reference to ((Comp(ment)(e. tar¬ 
get )>jmxtFocas( ); in Example 4 wcjrks lie- 
ciiLise JFactoiy allows you to rearrange the 
component’s creation order. (It’s called ' tab 
order/ although the JI)K 1.03 for Win32 
doesn't support tabbing.) By ordering die 
text fields consecutively, I ensure that 
nextEoais{J puts focus into die next text 
field and not, for example, in a button. 

Debugging 

After writing user code with Cafe's source 
editor and the class browser, I can com¬ 


pile and execute the applet from within 
the Cafe environment. 

And it doesn’t work, 

Cafe’s graphical debugger is extremely 
useful. Uie 1.20 version doesn’t ev^en re¬ 
quire TCP/IP. After setting breakpoints, I 
can step “over" methods, stopping on the 
next executed line, or step “"into” them, 
which takes me line by line into the 
method's source code. Cafe also has a 
data/object window' that displays the con¬ 
tents of class members and variables. 

The debugger has a few other features 
I haven't used, but they'd probably be 
helpful in other situations. The first is a 
Thread View w'indow that allows you to 
freeze and thaw' individual threads w^hile 
otliers continue to run. The second is a 
remote debugger for working with ap¬ 
plets running on anoiher machine. This 
could help find pesky problems that don't 
manifest themselves in a stand-alone en¬ 
vironment. 

Conclusion 

After a few^ roimtis of debugging, JavaTax 
Ls up and miming. As w'itli many software 
tasks, tlie pnigram logic is relatively sim¬ 
ple, yet the applet axjuired over 3500 linens 
of code. W'riimg it from scratch would be 
tough, hut using the riglii combination of 
tools make.s it a manageable task. 

Cafe and JFactoiy are both remarkably 
robust Ibr 1.x releases, l>ui they have tlieir 
share of bugs. However, my primary 
reservations about the Java language 
spring not from the availalile tools but 
from performance piohlems in tlie run¬ 
time environmeni. JavaTax runs fine in 
the applet viewer, but it brings Netscape 
3.0b4 to its knees. Nonetheless, I’m con¬ 
fident that these issues will resolve them¬ 
selves and that Java will soon mature into 
fornudable presence in the commercial 
d e vek )pment a ren a. 


For More Information 

S\nnanlec Carp. 

10201 Torre Avenue 

Cupertino, CA 93014-2132 

408-253-9600 

http/wwvv.Symantec. cx)m 

Rogue Wave Softw^are 
260 SW Madison Avenue 
Coivallis, OR 97333 
800-487-3217 

http:.//w'ww.r Ggu ew^ave. com 
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CALLING NATIVE CODE 


Calling 
Native Code 
from Java 



O ne of the benefits of program¬ 
ming in Java is that the Java Vir¬ 
tual Macliine (VM) liides platform 
differences. Applications can be 
developed once and run any¬ 
where a Java VM is impleinenLed. Unfor¬ 
tunately, that abstraction can get in the 
way of developing full-featured applica¬ 
tions. Although the AWT user-interface 
package, for instance, provides a reason¬ 
able way to write cross-platform GUI 
code, it lacks some basic services that 
users take for granted. For example, AWT 
doesn't offer clipboard support. So even 
though all major GUIs (Windows, Mac, 
Motif) have a clipboard, there's no way 
to access it from Java. While it's relative¬ 
ly U*ivial to code a Java clipboard, it 
would be nicer if the real clipboard 
were available, so data could be ex¬ 
changed with other applications* 

In this article TO use native code 
to implement a Java Clipboard class 
that does just that. Tliough the im¬ 
plementation of the cupboard class 
is for Win32, the basic principles of 
calling native code are die same on 
all Java platforms* 

The tools and documentation need¬ 
ed to write native methods are pro¬ 
vided in the Java Development Kit 
(JDK) (http:// w'ww.javasoft.com). I 
used JDK 1*0.2 and Visual C++ 22 
(4*x should work just as well) in im¬ 
plementing Clipboard. The complete 
souR’e cxxle :ind related files are avail- 


Rohi is a developer at Corel Carp., 
where he imrks on Jam-related soft¬ 
ware projects. He can be reached at 
rohik@coreL com . 


Defining and 
Implementing the Class 

Once a class with native metliods 
is defined, it's compiled like any 


able electronically; see “Progranuner's Ser¬ 
vices,*' page 3- 

Purists may question using native code, 
since it is nonportable. Java applets (as 
opposed to applications) aren't even al¬ 
lowed to load native libraries for security 
reasons. Still, certain projects demand ac¬ 
cess to native code* Anyone porting Java 


Declaring Native Methods 

Java doesn't support functions that exist 
outside a class—-all functions are meth¬ 
ods bound to some Java object. So how 
can Java programs call native C code, 
where objects and metliods don't exist? 

The answer Ls that native code must 
lie wrapped up in a Java class definitiQn. 
A Java class can be created w here 
the methods are declared in the 
standard fashion, but implemented 
in a C (or C++) library. Tliese meth¬ 
ods are called ''native" methods, 
and are identified by the native 
modifier. 

A native method is just like a nor¬ 
mal Java metliod except the imple¬ 
mentation Is absent. As Listing One 
(listings b^^ on page 33) illastrates, 
the Clipboard class has four native 
mediods. Notice that the class has a 
static block of code; this is how the 
library containing the native code is 
loaded. This library is a DLL on 
Win32, a shared library on tfie Mac¬ 
intosh, and shared object C*so) un¬ 
der Solaris. 


Sometimes there's 
no other choice 


Robi Khan 


to a new platform must use the native- 
code interface to call the underlying op¬ 
erating system Aids. People writing stand¬ 
alone Java applications often need to use 
existing code libraries until Java versions 
become available. In some cases, execu¬ 
tion speed may be critical enough that 
only compiled C/C++ code will suffice. 
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Httention Educators 

Dr. Dobb's wants to 
contact professional 
educators. We are 
starting a new program 
to provide information 
to the educational 
community. We ask that 
you please send us your 
name, institution name, 
address, phone number, 
fax number, and email 
address. We will contact 
you in the next few 
weeks and ask for your 
cooperation in this new 
endeavor. There will be 
no cost or obligation. 

Please centactusbij 

• email: 

jchristen@mfi.com 

• Phone (415) 655-4191 

• Fax: (415) 358-9749 

• Mail: Jenny Christen 
Community Outreach 
Coordinator 

Dr. Dobb's Journal 
411 Bore I Ave., Ste 100 
San Mateo, CA USA 


If you have any 
questions, please 
contact our Community 
Outreach Coordinator, 
Jenny Christen at 
(415) 655-4191, 


Other Java file (1 u sed the JDK 1.0.2 javac 
compiler) to produce a .class file; see 
Example 1(a). 

To allow access to the Clipboard ob\ea 
definition from native code, a header file 
and stubs file are needed. The ^fOK tool 
javah does this. It reads a class file and 
outputs a header with the equivalent C 
definition; see Example 1(b). (Note that 
javah takes a class name^—not a file¬ 
name—as its argument. Tliis means tliat 
any class javah can find, including the stan¬ 
dard java classes or those specified in the 
CLASSPATH, can be ased as an argument.) 
You can easily generate class definitions 
for any class in the CLASSPATld; see Ex¬ 
ample Kc). 

Tlie generated header file, Cliphoard.h, 
shows wliat the class looks like to C pro- 
gmms; see Listing Two. 

The ClassClipboard stTuci mirrors the 
definition of the Cliphoardchiis. The lone 
memlx:r variable in the class, the boolean 
m4to_empiy, is defined in tlie C version 
as a long. 

Javah generates a function prototype 
for each native method. 'Lhe function 
names are derived from tlie class name 
and methcxi name; tlie .string Cltpboard_ 
is prepended to the metiKxl names to form 
the function names. If Clipfx)ard were de¬ 
fined as pan of a jrackage (s^iy, my.uiClp- 
hoard) die Rinction names would begin 
with my_uiJCliplx}ard_ instead. 

Javah also does the work of generat¬ 
ing the stubs file. The stubs file is a C 
file that implements some glue code for 
the Java VM. Invoking a native method 
at run lime will cause the VM to call a 
stub function, which, in turn, will call 
the function implementation. The stubs 
are generated using the -stubs option, 


(a) 

javac Clipboard 

(b) 

javah Clipboard 

(c) 

javah java,io.Inputstrearn 


javah java,lang.String 


Example 1: (a) Compiling a class 
with naiim methods; (h) jamb reads 
a .class file and outputs a header; 
(cjgefterating class definitions. 


passing the .same class name used when 
generating the header. In this case, the 
stubs file will be Clipboard.c {javah 
-stubs Clipboard). 

Hie actual implementation of Clij^xjard, 
ClipboardlmpLcpp, is written in C++. Us¬ 
ing C++ for die implementation is just as 
easy as using C. The only requirement is 
that the class header be surrounded m an 
exlertt wrapper. Hie implementation 
file implements the functions prototyped 
in Clipboard.!!, calling various Win32 APIs 
to manipulate the clipboard; see Listing 
Hiree. 

Building the DLL 

Hie final step in the native implementa¬ 
tion is creating a DLL from the header, 
stub, and implementation files. The DLL 
111 create here is Clipboard.dlf 

No special work has to lie done to ex¬ 
port functions in the DLL— the stubs file 
already exporLs the required entry points. 
To build the library, the stubs and imple¬ 
mentation files (Clipboard, c and Clip- 
Ixiard^cpp) should lie aimpiled and link^ 
into the same DLL, Hie Java VM import 
library ( javai.lib, found in the JDK lib di¬ 
rectory) should also be linked in: It pro¬ 
vides entry points that allow the native 
code to instantiate and call Java objects. 

Hie Clipboard chss explicitly loads the 
Clipboard DLL in a piece of static code 
run at class-load time. Once die DLL is 
loaded, calls to any of the native meth¬ 
ods are resolved dynamically by the VM 
using GeiProcAddress(). You should be 
aware that if a native method is missing 
from the DLL, no error will occur until 
Java tries to call it (at which point it will 
throw a LinkageError exception). Simi¬ 
larly, if the entire DLL is missing or can¬ 
not be found, Java will throw an 
UfisatisJiedLinkError when SystemJoad 
is called. 

The sample ccxle includes an external 
makefile for Visual C++, just run nmake 
and all the necessary files will be built. 
The makefile requires that 

• The JDK 1.0.2 is properly iastalled. 

• 'Hie AL'r_BOO'rDlR environment vari¬ 
able is set to the JDK installation di¬ 
rectory. 

• The JDK tcx)ls are in the PATH. 


extern void Clipboard.elear(struct HGlipboard *bclip)r 

(b) extern void Clipboard^clear(struct HClipboard *this„ptr) 

C 

ifC unhandtthie_ptr)“>aiJto_empty ) 

Example 2: (a) Functions all have the same first parameter; f^eClipboard_getText 
function uses unhand to check the auto_empty member variable. 
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The virtual-machine headers that Clip¬ 
board uses are all part of the JDK’s in¬ 
clude directory. 

Runnmg and Debugging the 
Cfipboard Demo 

Once everything is built, you can run the 
demo Java application witli the Java in¬ 
terpreter by typing java NativeDemo. 

NativeDemo uses Clipboard to read 
the contents of the clipboard and prints 
the text to Sysiem.out Then it calls meth¬ 
ods to set and retrieve text from the clip¬ 
board. 

Clipboard's native code can be de¬ 
bugged by mnning java.exe in the Visu¬ 
al C++ debugger. Just rememl^r to spec- 
ily NaliveDerJto as tlie program aigument. 
Also, add Clipboard,dll to the list of ad¬ 
ditional DLLs in the debug-settings prop¬ 
erty page. 

Java Object Handles 

If you look at the function prototypes that 
javah generates for the Cliphoard class, 
you’ll notice that aU the functions have 
the same first p^imineter; see Example 2{a). 
This parameter is a handle to the objea 
on which d^e medtod operates. It Is sim¬ 
ilar to die C++ this pointer, except that it 
is explicitly declared, like the this point¬ 
er, the h^mdle provides access to the class- 
member data. 

Unlike C++ object pointers, Java object 
handles cannot be dereference with die 
-> or + operators. Instead, you must use 
the unbandO macro. This will return a 
pointer to the object s data. The Clip- 
board_getText function uses unhandf) to 
clieck the auto_empty member vaiiabie; 
.see Example 2(b). 

It may seem tedious to u.se the un- 
hand() macro to dereference object han¬ 
dles every time member data needs to be 
accessed, but it is necessary. Tf you deref¬ 
erence the iiandle and store the data point¬ 
er in a temporary variable, you run die 
risk of the VM moving the data some¬ 
where else when garbage collection oc¬ 
curs. The VM will prevent garbage col¬ 
lection if your data pointer is declared on 
die stack, but diis feature fails if you store 
the data pointer in a global. It is just safer 
to use unhandO all the time. 

In the same header, you'll notice that 
javah created a ty pe HClipboard as a han¬ 
dle to Clipboard —it just used the 
class name to make the type name. For 
classes that are in packages, javah gen¬ 
erates a handle name using the full pack¬ 
age and class name. For example, the 
class java.lang.String is referred to in¬ 
ternally with a handle named Hjam_ 
tang ^String. As another example, 
javadoJnputStream is referred to wdth 
Hjava_ io_JnputStream. 


Calling Java Code from C 

The Clipboard class not only caUs native 
code, but uses Java objects like String 
and InputStreams. Calling Java objects 
from C is done with a set of functions ex¬ 
ported from favai.dll, the virtual machine 
DLL; see Example 3Ca). 

The use of these functioas is similar; diey 
aJJ take an execudon environment as tlieir 
first parameter. An execution environment 
stores die state of die java stack— a zero 
is u.sualJy substituted for this argument to 
refer to the current environment. 

The function &m:tite_jai}a_coftstnictor 
instantiates a Java object, either by class 
name or by using previously loaded class 
information (point^ to by a ClassCt^^). 
Using preloaded class informadon is faster 
than resolving the class by name. Class in¬ 
formadon can be loaded using FindCkm, 
see Example 3(b). Wlien referring to a class 


by name, use the Rilly qualified class name, 
and replace the periods w idi forward slash¬ 
es; for example, die cla,ss ** java Jang. String" 
is referenced as “java/lan^String,” 

The execute_java_static_method func¬ 
tion calls a static method on a class. It re¬ 
quires the class information be found via 
FindClass first. The method to be called 
is specified by the method name. 

Similarly, execute_jaua_dynamic_ 
method calls a nonstatic method on an ob¬ 
ject. Instead of class info, you provide a 
liandle to the object on which the metJiod 
operates. Curiously, the VM does not pro¬ 
vide a FnidMethod call to bind to .static or 
dynamic mediods—you always have to 
specify the method name when caking it. 

Method Signatures 

Wlien calling a construaor or mediod, you 
have to supply a method signature. This 


Method: 

boolean startsWithfString prefix, Int toffset); 

Signature: 

”(Ljava/lang/String;I)Z” 

Method: 

void rnn(); 

: Signature: 


Method; 

Object put(Object key. Object value) 

Signatufe: 

"(Lj ava/lang/Object;Ljava/lang/Obj ect;)Ljava/lang/Obj ect:” 

Method: 

void writeChars(char char^array[]) 

Signature: 

“C[C)V:'' 


Figure 1: Method declarations and equivalent sigfiatures. 


(a) HObject ?=esecute_ java _cotia tract or (a true t execenv 

char Clas^Class *c, char ^signature* ... )r 

long execij;te_java_dynaiiiic_method( struct execenv *ee, 

HObject =i=obj. char =<'Tnethod_naiiie. char ^signature, ... ): 
long execute, java„static_fflethod (struct execenv 

ClassGlaaa *c. char =*'iaethod_rLaine. char -'•fsignature. ... 
GlafisClass -s^FindClasa (etruct axecenv char ^clasaname* 
bool_t resolve): 

(b) ClassClass ^ claes_infci: 

Hjava_lang^string *string_obj: 

class_info= FindClass( 0, java/lang/String^^ true )r 
string.obj = [Hjava^lang^stringJesecute^java^constructorC 0, 0, 

class_info> }; 


Example (a) Calling Jam objects from C; (b) class info can he loaded using 

FindClass. 


(a) 

char 

a3yte * 


a^yte 

= (char)execute_java_dyiiaiaic_iiiethod(0, obj_handle, 



^'sonieHethodRettirningByte", ) 

(t>) 

Hjava„lang_String ♦clip-String: 


long 

retval; 


retval 

“ execute^java_dyiiamic_tflethod(0. (Hobject ^)this,ptr, 



"geTTexr", " ()L j ava/lang/String ; ’0 ; 


Glip_string = fHjava_lang_String)retval■ 


Example 4: (a) Casting the return mine; casting the return value to an object 
handle of the appropriate type. 
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(a) SignalErrorC Ex&cEnv cher * 
excepticin_clas.sciflme * char * message) ; 

(b) execute, java ^dynamic.method (.*•/) 

If If except ioiiOccured( EE() ) ) [ 

// some exception happened, So ^catch* it 
exceptionClear (EE C))': 

// will atop unwinding of atadt 


Example 5: (a) Throwing Java ^ceptions from native code; 
(b) catching Java exceptions, 




SomeClass.aomeHethod C BSomeClaas ^ tMs_ptr ) 

[ 

monitorWait C obj.monitor Cthis^ptx)., timeout ) ; 
monitorNotify ( cibj_nxonitoT*.(thia_ptr) .); 
monitorNotifyAll ( • ohj .monitor (thiaj.ptr). } : 

} 


Example 6: Converting an object bandie into a Tnonitor. 


is a string that describes the parameters 
for the method. (The calls take a variable 
number of parameter arguments.) It re¬ 
sembles format strings. 

The method signature is a string of the 
form {<param_type>...)<return_type>. 
Parameter types are simple, one-character 
values for intrinsic data types or a class 
name for objects. If you supply an invalid 
method signature, an IncompatihleCiass- 
ChangeError exception will be thrown 
at run time. You should carefully exam¬ 
ine method signamres and their param¬ 
eters, since the parameters are untyped 
as witli printf— an incorrect fomiat string 
could cause a crash. 

If you look at tiie stubs file generated 
in the example Cliplxxird.c, you’ll see that 
javah inserts commenis with the method 
signature lor each of the native methods. 
If you are ever unsure about hos\' to code 
signatures, you can always use javah 
-stubs to generate them directly from a 
method declaration. You can also use the 
stubs file to see how intrinsic Java data 
types correspond to C data types; see 
Table I, Figure 1 provides .some example 
method declarations and equivalent sig¬ 
natures. 

Method Return Values 

Both Lxc^me_jam_siati€_ntetbcd 'm6 ex- 
eaite_jamjdyriamic_fneib(>drm}m hng 
If the metliod l^jeing called returns an in- 
triixsic type (whose size is less than or equal 
to a hn0, you can simply cast tlie return 
value to tfuit type; see Example 4(a). 

For methods that return objects, you 
am cast the return value to an object lian- 


die of the appropriate type, as in Clip- 
boardimpl.cpp; see Example 4(b). 

Working with Strings 

The VM provides a nutnber of useful rou¬ 
tines to convert strings from Java to C 
and back. The routines are well docu¬ 
mented in javastring.h in tlie JDK include 
directory. 

Catching and 
Throwing Exceptions 

You can throw java exceptions from na¬ 
tive code using die SignaiError function, 
see Example 5Ca). It w^ill instantiate an Ex¬ 
ception (or derived) object, and 

pass a message string to Fxc^tmfs con¬ 
structor. Note that SignaiError will not 
cause a C longjmp or C++ exception— 
die code will still have to use return goto, 
or C++ exception to exit out of the func¬ 
tion. Clipboardlmpi.cpp uses a utiiit>^ func¬ 
tion ThrovCliphoardExaption tliat, in turn, 
calls SignaiError. 

Catching Java exceptions is a little trick¬ 
ier, After looking through the JDK liead^ 
er riles, 1 turned up two macros in in- 
terpreter.h, exception Occu rred and 
exceptionClear that allow you to delect 
an exception and catch it. First use ex- 
ceptionOccurred to test if any exception 
has occurred. Then use exceptionClear 
to dear the exception state so tliat it does 
not continue unwinding the stack. These 
macTcxs require an execution environment, 
and do not accept zero as a default. A 
valid pointer to the current environment 
can be obtained via the EFO function; 
see Example 5(b). 


Unfortunately, these macros are not 
mentioned in the JDK online documen¬ 
tation, so they may not be safe to call 
Tlieir use is also limited by the fact dial 
you cannot detect the type of exception 
that occurred. 

Synchronization 

If native methods are declared as syn¬ 
chronized, no additional w^ork is needed 
to make them thread safe. The VM will 
properly synchronize native method calls. 

Functions corresponding to the wait, 
notify, and notifyAll mclliods are export¬ 
ed from the VM. The macro obJ_monitor 
converts an object handle into a monitor 
usable liy diese I'unctions; .see Fjcample 6. 

Other Native Code Solutions 

Both Microsoft and Netscape have alter¬ 
native methods of accessing native code 
from Java. Microsoft (wJiich t wns the ref¬ 
erence implementation of Java on Win32) 
has created a virtual macldne where die 
run-time layout t)f java objects matches 
that of COM (Component Object Model) 
objects. This makes Java objects caUable 
as COM objects from C/C++ code, and 
allows COM objects to be called from 
Java ctxle. This simplifies the calling pro¬ 
tocol between Java and C greatly, and 
may provide some execution-speed ad¬ 
vantages. (Details can be found on Mi¬ 
crosoft’s web site.) The big disadvantage 
is that it (jnly works w ith Microsoffs Java 
VM, and only on Window^s. The original 
native code interface at lea.st provides 
source compatibility among platforms. 
(Microsoft supports the existing interface 
as well.) 

Netscape has recently propo.sed an en¬ 
hanced version of the native code inter¬ 
face called ^JRl, (Java Kuntime Interface), 
It is the .same core set of functions, plus 
additional functionality, including excep¬ 
tion handling. iLs primary benefit over the 
Micrexsoft approacli is that it is a platform- 
independent API. It remains to lie seen 
w hether JavaSoft w^ill atlopt JRJ as a stan¬ 
dard Java API 

For mo.st developers, tiie native method 
interface^ with all its quirks, Ls tlie only 
solution for applications today. 

DDJ 


Java Type 

C Equivalent 

Signature 

long 

int64_t (64-bit integer) 

J 

integer 

long 

1 

byte 

char 

B 

char 

char 

C 

enum 

long 

E 

float 

float 

F 

double 

double 

D 

boolean 

long 

Z 

void 

void 

V 

JavaObject 

HObject * or derived 

L<classname>; 

Array of <lype> 

HarrayOf<type> * or 
HarrayOfObject * 

[<type> 


Table 1: How intrinsic Java data types correspond to C data types. 


30 


Dn Dobb% Sourcebook^ ISovember!December 1996 















CALLING NATIVE CODE 


Lisring One 

iaport java.io.+: 

public t!lfisa Clipboard 
{ 

static. 

I 

try I 

Syat^. IflfldLihraryC"Clipbo«d"} i 
] catch[UnBatlBfiedLinkSrror e) E 

Syste*.err.prlntlcE"Could not load Clipboard dll”); 

1 

public ClipboardEbswlesn auto.empty) f 
this.auto,empty ■ auto^empty; 

public native void cleat (>; 

public native void putTextE String clip.text J i 

public native String getText(H 

public native InpucStteaM getStregait) i 

boolean auTo.emptyi 


Listing Two 

/* DO I*0T EDIT THIS FILE - it is Kflctiiiie generated •/ 
#include <native.h> 

/• Header for ciasa Clipboard */ 

tlftidef _Included_Cllpboetd 
ttdaflne .IncludedLCllpboacd 


HANDLE hglb-clip-text; 
char * text: 
int textJLen; 

if( EOpenClipboard(NDLL} ) C 
ThrowCllpboardException("opening" ): 
return NULL: 

J 

// get the clipboard data 
hglb_olip_text - GetClipboardDataECF-TIXT); 

1ft h|lb_cllp,tiat == HULL j [ 
return NULL; 

) 

LESTR IpstClipHuffer; 

HJava_lang_Striiig * clip.atting: 

IpaaClipHuffer = [LPS'ni)GlobalLoek(bRlb_elip_tePct); 
iff IpaaClipBuffer = HULL ) { 

ThcovClipboardfirceptionC'l&cltliig"): 

return HULL; 

J 

clip-Btrins = makeJavaStrlngdpsiClipBuffer^ latrlenUpsaClipBuffec)) : 
Global Unlock £ hglb_clip_tHrt ]l; 

//if the suto.empty flag ia Set clear the clipboard 
Iff unhand(this,.ptr}->auto_aBpty ) £ 

EBptyClipboard£l: 

CloBeCllphoardO: 


typedef struct ClaesClipboacd C 
/♦boolean*/ long auto.eBpty; 
] ClasSClipboard; 

HandleTc (Clipboard )>; 


#tfdef _^cpluaplufl 
entem C 
#endif 

ertern void Clipboatd-clear fetmct HClipboard •); 

Struct Hjava,lang.String: 

extern void Clipboard_putTe*t£struct HClipboard *,struct Hjava-lanig-String *3; 
extern struct Hjava^lang.String ♦Clipboard.getTeitfatruet HClipboard ♦): 
atrviqti HjBva_la_lnpUtStreaBi; 

extern struct Hjava_io_InputStreaii • Clipboard, get Stream f struct HClipboard *) i 
ilifdef_eplufiplna 

ftendif 

Nndif 


Listing Three 


// JDK headsre do not Include #ifdaf „cpluseplu*/extern "C" guards 

// 60 we surround headers with extern "C" 

extern '*C“ t 

#include "Clipboard.h" 

il include “java.io-InputStreaH.h'* 

#include "java,io„StcIng^ufferInputsttaais.h’* 

if include "windows.h" 


static void ThrowClipboacdExc option (char * message) 

// throws a Java exception of type java.lang.Exception 

// and paaaea a |lven message atrlng to the exception claaa constructor 

Signalirror(0, "java/lang/Exception”, measage )j 


// empties the Clipboard 

void Clipboard-dear (struct HClipboard *\ 

BOOL enptied: 

^ emptied = BmptyCllpboardO : 

// putfl the given text String on the clipboard 
void ClipbosEd-putTextf 

struct HGIlphoard • thia_ptl:. 
struct Hjavs-lang-Etring * text.string ) 

HAHBil bglb_dip_text: 
char * text; 
iftt text-len: 

if£ 10penClipbqard£MULL3 l\ lEmptyCllpboardf) ) I 

ThrowClipboardEiceptlQn(“opening" )j 

return; 

I 

// nake a C string out of the Java String 
text = aakeCStrlngf teit_attinft ) i 
tejtt-len = Istr leu (text) j 

// allocate a global Muiory object for the text 
hglb_clip_teit = GlohalAUocf text_len +13: 

if£ hgLb_clip_text == MULL 3 C 

// couldn’t allocate block, so tbrcn# b Java exception 
TbrowClipboa rdExceptioni"allocating"]; 
return; 

) 


LPSTR IpazClipBuffer; 

// lock the clip buffer, and copy the string into it 
IpsaCllpBuffer ^ £LPS'ra3GlobdLock£hglh_clip_text): 
if( IpsaCllpBuffer == HULL ] C 
H couldn’t lock iMnary $0 thro-w Java exception 
^rowClipboardEiception("locking"} ; 

istrcpyC IpsaClipBuffar, text ); 

GlobalDnlocJtf hglb.clip.text J; 


return cllp^string; 

// returns the clipboard text data in a stream 
Strutt Bjava_lo_InputStreaa *Clipboflrd,getStreamf 
struct HClipboard * this.ptr ) 

Hjava^io-StringBufferlnputStraam * input,,stream3 
long retval; 

Hjava_lang_String * clip_atrlng; 


// call Clipboard.getString to get clipboard text 

retval * execute, j a va_dyusmlc_iiiethnd( 3. (HObject *)thJs_ptr. "getText". 

^(3 Ljava/lang/String:" ); 

tlip^atring = (fljave.leneStrlng ♦Jretval; 

// construct a StringBufferlnputStream from the string 

input^stream = £H Java. lo.S t rlngBuffer Inputs tr earn ♦) execute, j a va.constriictor £ 
0. ‘'Jave/io/stringBufferlnputStream", 0, ■’(Ljava/lang/Strlng;)", 
clip,atring 3; 

// StfibgBufferlnputStree* la derived fton tnputStreaa. 

// so this cast is perfectly valid 
return (HjavB.io.lnputStteeni •3±nput-Btreanj 


End of Listings 
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uted data management solution,, you can move. i^ % 
to ObjectStore PSE's big>j3i^bj^er/the market lead-\;;^^^^ 

n nhrArt(;tnrfi 


ing ObjectStore 

Visit our WeJ 
Java deskt3 


SetClipboartfBatxCCF.TEirT^. hglh.c lip .text ): 
CloaeCllpboard£3 * 

// tetuma the clipbpsrd tnxt rb a etring 
struct Hjava.lang-String *Clipboflrd.getTBXt£ 
struct HClipboard • this.ptrj 


Twenty Five Mail Road 
Burlington, M^chuseits 01803-4194 
1 800.962.9620 
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REAL-TIME CONTROL 


Java and Embedded 
Real-Time Control 


J ava was initially intended to be an 
implementation language for PDAs. 
Subsequently, development effort 
was retargeted to tlie needs of set¬ 
top boxes, CD-ROM software, and 
uliimately, the World Wide Web. Java is 
currently attracting most of its attention as 
a mediiim for portable distribution of soft¬ 
ware over the Internet, However, Java is 
much more than simply a language for 
adding animatic^ns to web pages. 

In many ways, Java is a better language 
ilian C and C++, two of die most papu¬ 
lar languages for current implementation 
of embedded real-time systems. If Java 
could he extended in ways that would al¬ 
low- it to suppon the cost-effective cre¬ 
ation of portable, reliable real-time appli¬ 
cations, this programming language wc^uld 
realize a much larger audience than just 
those implementing web applications. 
Some of the near-term applications for 
w hich a real-time dialect of Java would 
he especially well suited include 
PDAs, digital diagnosis (medical in¬ 
strumentation, automolive repair, 
electronics equipment), robotics, 
weather monitoring and forecasting, 
emergency and service vehicle dis¬ 
patch systems, in-veliicle navigation 
systems, home and business securi¬ 
ty systems, military .surveillance, radar 
and sonar analysis, air traffic control, 
and various telephone and Internet 
packet-sw itching applications. 

As defined and implemented by 
Sun, Java is not entirely appropriate 
for this domain. By extending the java 
language and libraries in ways that 
are compatiL'ile with Sun's original 


Kelvin, a former research scientist at 
lotm State Uniimsity's Center for Ad¬ 
vanced Technology Development, is 
cwrently president of NewMonics htc. 
He can be contacted at kdn@new- 
monics.com. 


Extending 
the language 
for real-time 
applications 


Kelvin Nilsen 


specifications, it is possible to create a lan¬ 
guage standafd tltat liener ,serves die needs 
of embedded-system developers. PEHC, 
short for “Portable Executive for Reliable 
Contror (and devebped by my company, 
NewMonics), is just such an extension. The 
PERC dialect of die Java language provides 
standard real-time libraries and special syn¬ 


tax extensions to allow you to describe 
real-time resouixx: requiiemenrs. Tlie PERC 
run-time environment provides real-time 
scheduling, on-die-fly schedu lability aniil- 
ysis, and real-time garbage collection. 

Code Reuse versus Embedded 
Real-time Constroints 

One of die primaiy^ benefits of the oliject- 
oriaiied paradigm is that previously de¬ 
veloped ccxle can lie easily incoqioi-ated 
into future products. For embedded- 
sysiems programmers, these benefits are 
manifest in a variety of situations. For in¬ 
stance, when a new product is first de- 
signe<l, devebpers am build on code pro¬ 
vided in the language's standard liliraries 
or in liliraries purchased from third par¬ 
ties. New oiijects witli semantic’s tliat close¬ 
ly resemtile existing ol:>jects are declared 
by simply inheriting from die original ob¬ 
ject definitions. Or, whem an existing prod¬ 
uct is modified, the ne%v functionality can 
often be added without dealing di¬ 
rectly witli die previously developed 
implementation. Instead, the new 
system simply inherits all of the 
fimciionalily cjf the original system, 
liven replaces or adds particular 
methods to achieve improved func¬ 
tionality. 

Rul reuse in an embedded real¬ 
time environment is especially diffi¬ 
cult, because you need lo take time 
and memory considerations into ac- 
cx>imi w henever cxxle is reused. Tliis 
is why Java without the PERC ex¬ 
tensions is not entirely appropriate 
for embedded real-time .systems. 
Shortcomings are in the areas of 
garbage collection, task scheduling, 
task synchronization, and am-lime 
analysis. 

G^iage Colkctiort In a neal-time 
application, it Is important tliai mem¬ 
ory will lie availalile for new objects 
when they need to be allocated. 
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Further, ir is importajit that background 
gaihage collection not impose long delays 
at unpredictable times. This would inter¬ 
fere witli your ability to demonstrate com¬ 
pliance with reahlime constraints. CurrcTit 
Java implementations do not address ii^'ues 
such as 

• Scanning. To distinguish live objects 
from garbage, most Java implementa¬ 
tions use a partially conservative scan¬ 
ning tecltnique in wUch memory words 
containing values that represent legal 
niemoiy^ addre.sses are assumed to rep¬ 
resent pointers. Since these words may 
actually hold integer or floating-point 
values, tlie use of conservative scanning 
techniques may cause the gatiiage col¬ 
lector to accidentally treat dead objects 
as live, resulting in memory leaks. 

• Fragmentation. Because most Java im¬ 
plementations use partially conservative 
garbage-collection techniques, it is not 
possible to relocate ail live objects in or¬ 
der to dehagment the memory heap. 
Over time, the cumulative eftecLs of hag- 
mentation make it difficult to allocate 
the large objects. This is especially trou- 
l>lesome for eml>edded systems tliat are 
expected to operate reliably for weeks 
at a time. 

• Scheduling. In Sun's Java implementa¬ 
tion, garbage coEection is implemented 
as a low'-priorit\^ background thread. If 
all applic:aiion threads are I/O bound, 
this approach works w'ell because 
gad>age collection is performed during 
times that die CPU would otlierw'ise be 
idle. However, if any application tasks 
are CPU-bound, the garbage collector 
is not scheduled for execution until die 
.system runs out of memory. Tlie first al¬ 
location request that cannot satisfied 
from the existing free pool triggers a 
stop-and-w^a it garbage collection of the 
entire system, forcing suspension of all 
odier tasks in the system. 

System information. By design, the 
Java run-time eiwdronmait does not allow' 
applications to deteniiine hoW' much mem¬ 
ory they require or how' much total mem¬ 
ory is available in the execution environ¬ 
ment, Tills makes it diffiaik for progntmnxas 
to detennine wliedier tlieir applicadoas can 
expect to mn reMably. 

Memory budgets. In Java, it Is common 
for niLiitipk activities to be running in an 
execution environment, so it is important 
for die system's run-time support to enforce 
memory budgets on each application. But 
the standard Java librarie^s provide no abil¬ 
ity to request or enforce memory budgets. 

Real-time scheduling. The tradition¬ 
al Java environment lacks mechanisms for 
real-time task scheduling. Applications c^ 


request to sleep for a specified number 
of milliseconds before continuing their ex¬ 
ecution, but there is no guarantee that the 
task will be suspended no longer than the 
requested amount of time^ and there is 
no guarantee that the task will have the 
highest priority at tlie time it is made ready 
for execution. Also, there is no way for a 
Java task to determine how many odier 
tasks are running on the system, their rel¬ 
ative priorities, and the portion of CPU 
time that diey consume, Tlius, tliere is no 
way to assure that a task will have suffi¬ 
cient CPU time to execute within its real¬ 
time constraints. 

Syiichroiii2ation. When it comes to 
task synchronization, java uses monitors 
(identiTied by the keyword) 

to procea critical sections of code from si¬ 
multaneous acceSvS by multiple tasks. Once 
a task has entered into the monitor that 
corresponds to a partiajlar object, no oth¬ 
er task can access that object’s monitor 
code until tlie first task has exited die mon¬ 
itor. Note tiiat in order to analyze the time 
required to perform certain actions, a real¬ 
time developer must know how*^ long each 
task might have to wait for entry to mon¬ 
itors. The information required to perform 
diis analysis is not generally available. That 
information Is basically of tliree types: 

• Number and priority of competing tasks, 
In the highly dynamic Java execution 
environment, the number and priorities 
of other tasks that desire to share ac¬ 
cess to an object are difficult to deter¬ 
mine and may vary throughout the ex¬ 
ecution of a task, 'fhus, it is difficult to 
determine hcfw many other tasks might 
be ahead of a task in the queue await¬ 
ing access to a shared object’s monitor. 

• Time spent within monitors. Java im¬ 
poses no restrictions on the complexi¬ 
ty of code contained witliin a synchro¬ 
nized method. The ccxle may comprise 
unbounded loops, dynamic meiliod in¬ 
vocations, and nested entry into other 
monitors. Newjy loaded class libraries 
may include j^fnchronized statements 
tliat lock particular objects. Thus, it is 
nearly impossible to determine how 
much time each competing task might 
spend w'ithin a monitor. 

• Priority inversion. Java's standard libraries 
fail to specify tlie scheduling model and 
fail to specify protocols for avoiding pri¬ 
ority inversion. This means that real-time 
programmers would not be able to an¬ 
alyze blocking behaviors even if they 
had perfect knowledge of the iinple- 
mentations of all die tasks that comprise 
the combined system workload. 

Introspection. Since the time and 
memory requirements of Java programs 


are not known until the bytecodes have 
been loaded into tlie executing environ¬ 
ment, the envuonment must pro\ide mech¬ 
anisms to support run-time analysis of the 
follcwing resource requirements: 

• CPU time. Java’s standard libraries fail 
to provide a [irotocol whereby newly 
loaded tasks could detennine how much 
CPU time they require to execute reli¬ 
ably on the host platform. 

“ Memory. Java’s standard libraries lack 
mechanisms to enable applications to 
determine how much memory’ is re¬ 
quired to represent particular objects in 
the local execution environment. 

• Workload. Java’s standard libraries pro¬ 
vide no mechanism to enable applica¬ 
tions to determine the total system- 
memory capacity or to detennine how 
much CPU time and memory^ are required 
by tlie other tasks concurrently execut¬ 
ing on the host machine. 

Although not as fundamental as the 
aforementioned probleni.s, design trade¬ 
offs made in most current Java imple¬ 
mentations have been biased by priorities 
and mindsets lliat are inconsistent with 
the neecb of embedded real-time system 
development. Their economies differ sig- 
mficantJy from tliase of traditional desktop- 
application developers. For example, cur¬ 
rent Java implementations are not space 
efficient. Many use a 32-bit w^ord to rep¬ 
resent a Java b>ae. And the choice to use 
partially conservative garbage cofleaion 
was biased by a w^orking environment in 
which memory is abundant and where 
high-speed disk drives niiike virtual mem¬ 
ory readily available. 

Another exi^mple of the tension tew een 
desktop and embedded real-time devel¬ 
opers is tlie use of dynamic compilation. 
In order to achieve liigh perfomiance. Sun 
suggests lhat selected code segments be 
translated Ifom Java bytecodes to native 
machine language. Detennination of the 
segments to translate is based on recent 
execution history. Routines that prove 
themselves to be "'hot spots’’ are translat¬ 
ed on the fly. The intCTTuptions required 
to perform translation, which ocair at un¬ 
predictable times, complicate analysis of 
task execution times. 

Standard PERC Libraries 

PERC is designed to let you develop reli¬ 
able portable real-time software compo¬ 
nents, As space does not allow for a com¬ 
plete description of die proposed 
extensions, I w^ill provide only an overview 
of w ork that is under progress. For more 
cromplele descTiptions, see my p:tper “Real- 
Time Java (v.1.1)” at http://www.new- 
monics.com, and my article “Issues in die 
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Etesign and linpienimtation of BeaETiine 
Java” K jmja Devek^)er'sJuunial 1996. 1(1)). 

Standard Real-time API 

Tlie PERC real-time API includes mecha¬ 
nisms that enable you to analyze and 
measure the times required to execute par¬ 
ticular code segments, to analyze the mem¬ 
ory required to represeni paiticukr objects, 
and to abstract access to persistent objects 
ret:>resented by tlash or battery-tecked RAM. 
Real-time applications are structured as ac¬ 
tivities, each of wliich is comprised of one 
or more real-time tasks. Each task Is com¬ 
prised of c^sseniial ^md optional components. 
PERC provides on-the-fly analysis capabil¬ 
ities to enable activities to negotiate for the 
resources to execute botli components. It 
Ls the PERC programmer’s responsibility to 
decide how much of each task Ls essential 
and hc3w^ much Ls optional. In general, it Ls 
much less costly to provide die resourc'es 
required of optional components Uian to 
provide guaranteed resources for essential 
functionality, PERC programiner.s should 
take these eccmomic factors into account. 

A typical execution environment would 
have multiple real-time activities execut¬ 
ing at any given time. For example, one 
activity might l>e displaying a full-motion 


television-like news feed while anotlier 
takes responsibility for tracking the user's 
pen motions and a third maintains a video 
conference connection. Each activity Ls ac¬ 
companied by oonj^ureO tind 
metltods. 

Before a new real-time activity is exe¬ 
cuted, it is ^'introduced” to the local real¬ 
time executive. The executive, in mm, in¬ 
vokes the activity's configure() metliod, 
which was provided by iLs developers. It 
is die responsibility of diis methcxl to de¬ 
termine the activity’s resource needs in 
the local execution enviionmeni. lliLs con¬ 
sists of measuring each task’s CPU-lime 
requirements and compuiing the com¬ 
bined memory needs of all the tasks that 
compri.se the real-time activity. The con- 
f\gUTe( } mediod returns a representation 
of the activity’-s minimum and desired re¬ 
source allocations to die executive. 

Once the amjigiirei ) metliod has re¬ 
turned, the executive endeavors to satis¬ 
fy the aaivity's rescjurce requests. Tlie ex¬ 
ecutive proposes a resource budget to tlie 
real-time activity by invoking the activi¬ 
ty’s negQtiatd) method. Since the real¬ 
time executive may propose to budget 
fewer resources than were requested by 
the activity, the activity has die opiion of 


rejecting the proposed budget. If the pro- 
poscd budget is rejected, die real-tirt^ ex¬ 
ecutive may decide not to allow the new 
activity to be added to the system work¬ 
load. Alternatively, the executive may re¬ 
claim resources previously allocated to 
other activities (by renegotiating their re¬ 
source budgets), then propose a revised 
budget to the new activity by once again 
invoking its negotiate() method. 

Syntax Extensions to Java 

D^elopets who use C or C++ must rely on 
prerun-time analy.sis and opemting-system 
services to enforce real-time constraints. 
ThLs Ls undesirable for a number of reasons: 

• The source code alone is not sufficient 
to represent the funciional and real-time 
semantics of die software. Ttie real-time 
constraints are scattered among speci¬ 
fication documents, developer logs, and 
automattxl scripts tliat perfonn analysis 
of execLition-lime requirements. 

• Often, the operating-system services are 
not pan of the ANSI C standard. Use of 
these services makes the code non¬ 
portable among openiiing .systems. 

• Since the operating-system services are 
seen by the programming-language 
ctJUipiltT as subroutines thal are outside 
its domain of analysis, ihe compiler is 
generally tmable to inline or otherwise 
optimize their implementations. 

For lliese reasons, we have incorporat¬ 
ed two special syntaxes into the design 
of PERC. These syntaxes are designed to 
simplify programming, ease the burden of 
software maintenance, and improve im¬ 
plementation efficiency. 

Kathei' tlian rely entirely on the use of 
synchronized code segments (for which 
blocking limes are difficult lo analyze), 
PERC firovides a meclianism known as an 
“atomic statement." Tlie body of an atom¬ 
ic .suitement is executed either to cximple- 
tion or not at aU. To the programmer, an 
atomic statement resembles die disabling 
of iniemipts. Mowever, die implemenlation 
may differ. In particular, a hard-real-time 
implementation of PFRC might verify that 
sufficient CPU rime remaias in die cunent 
time slice to complete execution of the 
atomic statement liefore allowing control 
to cTtter into the aitimic statement's lx)dy. 
Without lids check, the inability to inter- 
nipt the atomic statement might push all 
otiier tasks in die system off schedule. 

PERC requires the Ixidy of an atomic 
statement to be execution-time analyzable. 
The PFJC stiindard defines a subset of Java 
for wliicfi it is possible, tliiough on-the-lly 
analysis, to determine worst-case execu¬ 
tion times. For single processor imple¬ 
mentations, die use of an atomic statement 
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for real-time synchronization scales much 
more easily than the use of synchronized 
statements, because there is no need to an¬ 
alyze blocking times. If a partial lar task has 
been granted CPU time to execute, tlten it 
also has access to whatever atomic state¬ 
ments may lie along its execution path. 

A secT^nd syntax introduced for the pur- 
pase of enabling programmers to describe 
real-time requirements is a “timed state- 
nroit" The control clause of a timed state¬ 
ment represents an upper bound on the 
amount of CPU time the body of the timed 
statenxait Is allowed to execute, including 
tlie CPU time inherited by other tasks that 
happen to own access to critical monitors 
at times tliat diis task desires access. If the 
IxKly of the timed statement is still execut¬ 
ing at the end of its allotted time, the body 
Is aborted by raising a timeout exception. 

Example 1 demonstrates examples of 
both control stmcture extensions. In tliis 
code, the application refines approxima¬ 
tion X as many times as it can within a 
10-ms time budget. Tlie variable j counts 
the number of times jc’s value is refined. 
The significance of the atomic control 
stmcture in tltis code is to make sure that 
the body of the timed statement is not 
alx)rted betw^een tiie assignment to x and 
tlie increment to i 

PERC Development Environment 

Figure 1 illustrates the PERC development 
and execution environment. p2jpp is a 


X - computGApproximatioiiO r 
i = 0: 

timed (10 ms) [ 
for ( : i ) { 

z = refineApproximation(x); 
atomic [ 

3C = a: 
i-H-j 

} 

} 

} 


Example 1: Examples of control 
structure extensions. 


preprocessor that converts the timed and 
atomic statements into standard Java 
source code. Tlie output of p2jpp Ls ready 
for a traditional Java compiler, such as 
Sun's javac. Note that PERC source code 
can also be translated directly to Java byte¬ 
codes by Percolator (a NewMonics prod¬ 
uct). Percolator outputs bytectxles that are 
essentially the same as Sun's javac. How¬ 
ever, the class files emitted by Percolator 
also include special attribute infonnation 
to identify particular parts of the program 
that require real-time detenninism. The 
PERC virtual machine uses this attribute 
information to assist in its analysis of 
worst-case execution times. Utis attribute 
also enables it to perform transformations 
on the bytecode that will allow the real¬ 
time program to run much faster than 
w^ould be possible williout tlie transfor¬ 
mations. 

Exeatiion of PERC programs on a tra¬ 
ditional Java virtual machine with accom¬ 
panying PERC libraries Ls le.s.s efficient and 
less predictable than execution on a PERC 
virtual machine. For example, the tradi¬ 
tional Java virtual macliine 

• Does not understand the special at¬ 
tributes that are inserted by Percolator, 
As a result, it is not able to perform die 
transformations necessary to improye 
performance and determinism. 

• May be running as a task witiiin a time¬ 
sharing system that is unable to provide 
any guarantee of wJiat fraction of tlie 
.system's CPU time will be dedicated to 
the Java \tirtuaJ machine. 

• Is unable to perform schedulability an¬ 
alysis so it cannot guarantee tasks tiiat 
tiiey will execute wltiiin their real-tin^ 
constraints. 

• Lacks the ability to distinguish among 
memory allocated to different real-time 
activities. Thus, it cannot enforce mem¬ 
ory budgets on particular real-time tasks. 

• Probably lacks support for real-time 
garbage col lection. There is no way 
for tlie PERC program to configure the 


system's garbage collector to support 
a guaranteed rate of new memory al¬ 
location. 

Neveriheiess, for applications con¬ 
strained by real-time expectations, exe¬ 
cuting PERC on a tiaditional virtual ma¬ 
chine offers important benefits over 
attempting to achieve real-time determin¬ 
ism witiioul die use of PERC extensions. 

In particular, application programmers 
are provided witii standard notations in 
wliich to encode the desired real-tinx^ be¬ 
havior as pan of their source program. 
Tills contributes to die ease of long-term 
softw’^are naaintcTtance. 

Also, although the exeaition environ¬ 
ment may not lie able to satisfy all the de¬ 
sired real-time constraints, the PERC li¬ 
braries are able to determine where 
real-time performance is falling short. Tiriis 
information can be used by the run-time 
system and the application code to dy¬ 
namically adjust service quality and load 
balancing. 

Of course, for best perfonnance and 
real-time determinism, PERC bytecodes 
should Lx^ run on a PERC virtual machine. 
Note that the PERC virtual machine can 
am lx>th Java and PERC code. If a work¬ 
load contaias a mixture of PERC and Java 
prcjgramSj the fonner are provided with 
their resources first, and tlie latter receives 
wdiatever is leftover. 

Further information 

Because of space coastraints, IVe omitted 
many details about PERC. For more in¬ 
formation, check out help://www.new- 
monies.com. We encourage open disems- 
Sion and constructive criticism of this 
eirolving standard. Please send comments 
to real-time-java@iastate.edu. 
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JAVAOS 


JavaOS: An Operating 
System for Small Devices 


J ava haii come a long way since its in¬ 
troduction last year as a net-capable 
ptogramniing language. To cope with 
all the market and product activity^ 
Sun Microsystems spun off a sub¬ 
sidiary, JavaSoft, to focus on the myriad ap¬ 
plications of Java. At Sun's JavaOne con¬ 
ference, the company showcased Java as a 
solution for ever^iing you miglit want to 
do on the Internet or with an intranet— 
client/server computing, obfect-m^inagement 
systems S la OpenDcx: or ActiveX, web 
servers, and of course, the ever-popular 
wel> content creation. 

Surprisingly, Sun didn't stick to its tradi¬ 
tional large^ di.stributed-system arena. It 
also announced JavaOS, a complete oper¬ 
ating system vvith a minimalist set of ap¬ 
plication and network services and a PDA- 
size memory footprint. You can even strip 
out part of die traditional operating- 
system services (window manage- 
mcnt, for instance) and fit JavaOS into 
a memory space appropriate for an 
emliedded processor. Available by the 
end of 1996 , JavaOS may do the same 
thing to the PDA and emliedded mar- 
keLs that Java has done to the Inter¬ 
net^—wreak havoc. 

A Traditional^ Javo 
Implementation 

You can implement Java in virtually 
any type of computer architecture, 
whether an operating system or a mere 
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application, by porting die Java Virtual Ma¬ 
chine and die Java Foundation classes to the 
architecture. The run-time environment 
doesn't matter as long as the Java API re¬ 
mains intact so that Java applets can run. 

Figure 1 shows a Java implementation 
as part of a conventional operating sys¬ 


tem. The topmost layer, the Java Foun¬ 
dation, Abstract Window Toolkit (AWT), 
and Network and I/O classes are all writ¬ 
ten in Java, The run time, including the 
interpreter and garbage colleaor, is writ¬ 
ten primarily in platfonn-independent C. 
There is some platform-specific code in 
both C and assembler, but it’s minimal. 
There are also libraries like Libawt and lib- 
net that map the platform-independent 
classes to OS-specific APIs. All of this sits 
on top of the native operating system. 

Java requires several types of operating- 
system support: 

• Context Switching. The host system must 
provide some type of context-switching 
mechanism. If it also provides support 
for threads, Java can take advantage of 
that to optimize its own multithreading. 
Memory^ Allocation. The run time 
manages its own heap and 
gari:xage collection, but it still needs 
a low-level memory-allocation 
mechanism. 

GUI Toolkit. Java has platform- 
independent windowing and 
graphics tool kits, but it relies on 
the host system to provide a set 
of graphics primitives to imple¬ 
ment those tool kits. 

Networking. The host system 
needs to provide a suite of stan¬ 
dard networking protocols. Java 
provides the abstraction to use 
those protocols. 

I/O, Java has standard classes for 
streams and files. In addition, Java 
applets assume that a device has 
some standard I/O devices like a 
keyboard, mouse, and display. 
The platfonn needs to provide 
basic I/O services to support 
these classes. 
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JAVAOS 


When porting Java to a spjedfic platform, 
you have lo map these Java classes and 
services to tiie native operating system. 

JavaOS: Na Host Required 

When Sun created JavaOS, it essentially had 
to remove as many of the platform de¬ 
pendencies as possible and migrate diem 
to platform-independent code. First, Sun 
implemented die srnallest possible set of 
kernel services needed to support the vir¬ 
tual machine. Tlie company then used tlie 
virtual machine and the new minima list 
kernel to implement all tlie taher services— 
GUI support, networking, I/O drivers, and 
a file system. Finally, Sun checked its work 
to make sure it supported tlie hill Java API. 
Applications written for JavaOS should run 
on any Java-enabled platform. Figure 2 
shows die JavaOS architeciure. 

The JavaOS kernel is not a general- 
purpose kernel. It's designed specifically 


to support JavaOS. Tlie kernel provides 
three basic types of sei-vices: 

• Bcxiting. The bcx>t-strap code allocates 
memory for the Java heap, DMA re^ons, 
and I/O device registers. It also detects 
hardware devices and maps them lo the 
appropriate device drivers. 

• Traps and Interrupts, Hols code provides 
traditional I/O services, interacting with 
hardware devices and passing informa¬ 
tion to and from device drivers. 

• Tliiead Support. This code .supports con¬ 
text switching for die virtual machine. 
The Java Virtual Machine uses threads 
quite a bit. A typical system has do2ens 
of tlireads running at any one time. 

Tins minimalist kernel has several ad¬ 
vantages over a more iraditional, general- 
purpose operating system. First, its mem¬ 
ory footprint is modest ( more about tliat 


shordy) l'>ecause it only provides a small 
set of critical functions. Second, because 
of die memory protection provided by die 
Java programming language, all applica¬ 
tions can run in a single address space. 
This minimizes context-switching over¬ 
head. It also means that the entire systetn 
can run in supervisor mode. Again, this 
minimizes ope rating-.system overhead, 
simplifies programming, and makes the 
system fasten 

JavaOS doesn’t require a memory-man¬ 
agement unit (MMU). If one ts present, 
the operating .system can use it to make 
several disjoint address spaces appear 
contiguous. After the system boots up 
and the MMU is initialized, it's not used 
again. 

Higher-Level Components 

The Java Virtual Machine does more dian 
just interpret b)1;ecodes. It Is also respon¬ 
sible for memory management, exception 
handling, and thread coordination. The 
JavaOS virtual machine is almost identical 
to the one provided widi the Java Devel¬ 
opers Kit 1.0. The memory-management 
and garbage-col lection algorithms have 
lieen slightly modified. 

The device drivers are writtcm entirely 
in Java (JavaSoft is in the process of defin¬ 
ing a Java Device Driver interface for third- 
party devek^ix^rs). Sun was alile to do this 
iiy abstracting two operations into small 
C support classes: a MemoiyObject class 
that give.s drivers access to specific mem- 
oiy locations, and an intermpt-dispatch 
class. The methods of these classes are 
not made available to Java applications, 
JavaSoft claims to have more tlmn a dozen 
drivers currently finished. 

Like the device drivers, tlie network pro- 
tcxols are also written in )ava. Uie current 
suite includes TCP, LID'p, IP, and ICMP. 
JavaOS also u.ses DNS and NIS for host- 
name Irx^kup and login .services, plus DHCP 
for dynamic IP address allocation, mini¬ 
mizing network-administmtion lequiieinents 
for connectable devices. There is a Net¬ 
work File System (NFS) client and support 
for Simple Network Management Protocol 
(.SNMl^) so that JavaOS device.s can lx man¬ 
aged in a network environment. 

JavaSoft rewrote much of the win¬ 
dowing system, making it more appro¬ 
priate for the JavaOS environment. AJ- 
thoLigh it is a full implement of the Java 
Abstract Wintlow Tcx)lkit (AWT), the win¬ 
dowing system is designed to take ad¬ 
vantage of its a priori knowledge of the 
lower levels of die operating system. The 
lowest levels of the graphics libraries are 
written as native methods because they 
need direct access to frame buffer mem¬ 
ory Icxraiions. The rest of die AVCHT is writ¬ 
ten in Java. 
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Figure /; A Jam implementation as pari of a conwniionai operating system. 
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Performance 

JavaSoft lias (so far) done litde JavaOS per¬ 
formance optimization, and native meth¬ 
ods are not extensively used. Also, the 
current implementation doesn't use a just- 
in-time compiler to improve performance. 
Nonetheless, JavaSoft is very pleased with 
the preliminary performance of the oper¬ 
ating system. 

TCP/IP throughput, about 500 Kbits/sec, 
is twice the original goal, and more than 
suitable for web browsing. Also, JavaSoft 
is pleased with the benchmarking they 
have done to date, JavaSoft attributes the 
good performance to the elimination of 
several layers of operating-systetn over¬ 
head that more traditional, general- 
purpose platforms require. 

On the high end, a complete JavaOS 
system, including the HotJava browser, 
can fit into 4 MB of ROM and 4 MB of 
RAM. Tire ROM includes: 

• JavaOS, including the kernel, drivers, 

virtual machine, and standard classes, 

• The windows, graptiics, and network¬ 
ing components. 

• HotJava, 

• About 1 MB for various fonts and styles. 

If the ROM code is XIP (execute-in- 
place), which JavaSoft claims is possible, 
tlie dynamic RAM requirements are alx>ut 

2.5 MB for JavaOS and Hotjava, leaving 

1.5 MB for downloaded HTML pages, ap¬ 
plets, and images. If you create a system 
that doesn’t need windowing or HotJava, 
the memory requirements are reduced by 
approximately half, 

Although JavaSoft presents JavaOS as 
ideal for Internet Appliances, the compa¬ 
ny also likes to fit it into the bw-end em¬ 
bedded system mtiiket. In its smallest con¬ 
figuration, with no graphics code, no 
nem^ork support, no font support, and no 
browser, JavaOS can fit into about 128 KB 
of RAM and 512 KB of ROM. You also 
need additional RAM for applications and 
run-lime requirements. 

Current Status 

JavaSoft has promised delivery to qualified 
licensing partners by <34, 19^. The com¬ 
pany plans to unveil real praducLs as ear¬ 
ly as January 1997. WMe that might seem 
a bit quick, some Sun partners have prob¬ 
ably already been worl^g with JavaOS for 
.several months. JavaOS turrenily runs on 
two chip sets—SPARC microprocessors, 
and Intel x86-compatible processors. Java¬ 
Soft has stated that tire platform is being 
ported to other instruction sets. 

One bgical JavaOS processor is the Mii- 
subislii M32RAT a 32-bit RISC CPU with 2 
MB of on-board DRAM, a 2-KB SRAM 
cache, on-chip DSP capabilities (including 


the appropriate hardware arithmetic sup- 
pon), plus memory controller and periph¬ 
eral circuits. Clocked at 66 MHz, the 
M32E/D is lated at 52.4 Dhiystone 2T MIPS. 

Mitsubishi has been partnering with Sun 
for several years. In May, Mitsubishi an¬ 
nounced that it had ported Java to this 
chip, running on top of an unspecified 
microkernel. Because of the JavaOS ar¬ 
chitecture, once Java is ported, it shouldn't 
be too tough to port the complete oper¬ 
ating system. 

Another logical chip for JavaOS is Sun’s 
own JavaChip. Announced in February, 
JavaChips come in three flavors: small, 
medium, and large. Each contains a 
silicon-based Java interpreter that can run 
Java code right from startup. The three 
chips differ primarily in clock speed and 
additional on-board silicon. The low-end 
picojava should be sampling by Q4,1996. 

AltliougJi arcliiteaural details have been 
sketchy, these chips should have the ap¬ 
propriate hooks to run a system like 
JavaOS, or perhaps Sun will create yet an¬ 
other JavaChip specifically for JavaOS. 

The Grand Scheme of Things 

At first glance, JavaOS on a hand-held de¬ 
vice appears to be the quintessential Net¬ 


work Computer, optimized for web brows¬ 
ing, rich content, and industry-standard con¬ 
nectivity. JavaSoft is so busy focusing on 
its basic tedinobgies, however, dial it hasn't 
started thinking about otlier aspects of the 
hand-held market— applications software 
designed specifically for mobile comput¬ 
ing, desktop connectivity, and the like. 

Manufacturers may find that, instead of 
hot web browsing, consumers prefer a 
Newton, with a good set of PIM applica¬ 
tions, Riruling Apple's Internet Enabler 
stack and AllPen's NetHopper (limited to 
text-only Web brow^sing), Or Microsoft’s 
long-rumored Pegasus operating system 
widi a built-in HTML browser, PIM soft¬ 
ware, and tight Windows desktop inte¬ 
gration may be more compelling. 

However the market shakes out over 
the next few years, it's clear that JavaSoft 
will alter die hand-held device landscape 
if the company continues iLs efforts. At the 
very least, JavaSoft has tossed its hat into 
a part of the computer arena that is still 
viewed with skepticism by some platform 
creators. Once manufacturers release 
JavaOS-based devices, we'll find out if 
consumers care. 
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RAMBUNGS IN REAL TIME 


Quake’s Lighting Model: 
Surface Caching 



D uring my senior year in college, I 
discovered computer games. Not 
Wizardry Of CbopHfierox Ultima, 
because none of those existed 
yet—the game that hooked me 
was the original Star Trekg^mfi, in which 
you navigated from one 8x8 quadrant to 
another in search of starbases, occasion¬ 
ally firing phasers or photon torpedoes. 
This was les.s exciting than it sounds; af¬ 
ter each move, the current quadrant liad 
to be reprinted from scratch, along with 
the current stats “ and the output device 
was a 10-cps printball console. A typical 
game took over an hour, during which 
nothing particularly stimulating ever hap¬ 
pened (Klingons appeared periodically, 
but they politely w^aited for your next 
move before attacking, and your photon 
lorpedoes never missed so the outcome 
was never in doubt), but none of dial mat¬ 
tered; nothing could detract from the sheer 
thrill of being in a computer-simulated 
universe. 

Then the college got a PDP-11 with four 
CRT terminals and suddenly Star Trek 
could redraw in a second instead of a 
minute, I3etter yet, I found the source code 
for the Star Trek program in the recesses 
of the new system—the first time fd ever 
seen any real-world code other than my 
own— and excitedly dove into it. One 
evening, as I was looking through the 
code, a girl at the next termina! a,sked me 
for help getting a program to run. After I 
had helped her, eager to get to know her 
better, I said, “Want to see something^ This 
is the actual source for the Star Trek 
game!” and proceeded to page through 
the code, desatbing each subroutine. We 
got to miking and eventually I worked up 
the nerve to ask her out She said sure, 
and we ended up having a good time, al- 
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though things soon fell apart because of 
her two or three other boyfriends (I nev¬ 
er did get an exact count). Tlie interest¬ 
ing tiling, though, was her response when 
I finally got aaiund to asking her out. She 
said, “It's alx)ut time!” When I asked what 
she meant, she said, “IVe been trying to 
get you to ask me out all evening— but 
it took you forever! You didn’t actually 
think I was Interested in that Star Trek 
program, did you?” 

Actually, yes, I had thought that, be¬ 
cause I was interested in it. One thing 1 
learned from diat experience, and have 
had reinforced countless times since, is 
that we—^you, me, anyone who programs 
because they love it, who would do it for 
free if necessary— are a breed apart. 
We’re different, and luckily so; wliile ev¬ 
eryone else Ls worrying about downsiz¬ 
ing, we’re in one of the hottest industries 
in tile world. And, so far as 1 can see, the 
biggest reason weTe in such a good sit¬ 
uation isn’t intelligence, or hard work, or 
education, although those help; ifs diat 
we actually like this stuff 

It’s important to keep it that way. IVe 
seen far too many people start to treat 
programming like a job, forget the joy of 
doing it, and burn out. So keep an eye 
on how you feel about die programming 
you’re doing, and if it’s getting stale, it’s 
time to learn something new; there's plen¬ 
ty of interesting programming of all sorts 
to be done. Follow^ your interests— and 
don’t forget to have fun! 

Lighting 

As I’ve mentioned in previous columns, 
I’ve spent the last year and a half work¬ 
ing with John Carmack on Quake's 3-D 
graphics engine. John has faced several 
fundamental design issues while archi¬ 
tecting Quake. I've wTitten in past columns 
about some of those issues, including elim¬ 
inating nonvLsible polygons quickly via a 
precalculated potentially visible set (PVS), 


and improving perfomiance by inserting 
fXJtentially visible polygoas into a global 
edge list and scanning out only the near¬ 
est polygon at each pixel. 

For the rest of this column. I'm going 
to talk about another, equally crucial de¬ 
sign issue: how we developed our light¬ 
ing approach for the part of the Quake 
engine that draw^ the world itself, the stat¬ 
ic walls and floors and ceilings. Monsters 
and players are drawn using completely 
different rendering code, where speed is 
die overriding factor. A primary goal for 
the world, on the other hand, was to be 
as precise as possible, getting everytliing 
right so that polygons, textures, and so¬ 
phisticated lighting would be pegged in 
place, witii no visible shifting or distor¬ 
tion under all viewing conditions, for max¬ 
imum player immersion—all with good 
pertbrmance, of course. As I'll discuss, tlie 
twin goals of perfonnance and rock-solid, 
complex lighting proved to be difficult to 
achieve with traditional lighting ap¬ 
proaches; ultimately, a dramatically dif¬ 
ferent approach was required. 

Gouraud Shading 

The traditional way to do realistic lighting 
in polygon pipelines is Gouraud shading 
(also known as “smooth shading”), Gou¬ 
raud shading involves generating a light¬ 
ing value at each polygon vertex by ap¬ 
plying all relevant world lighting, linearly 
interpolating between lighting values dowm 
the edges of the polygon, and then lin¬ 
early mterpolating between the edges of 
the polygon across each span. If texture 
mapping is desired (all polygons are tex¬ 
ture mapped in Qtmke), tlien at each pix¬ 
el in each span, the pixel's correspond¬ 
ing texture-map location (a “lexel”) is 
determined, and the interpolated lighting 
is applied to the texel to generate a fmal, 
lit pixel. Texels are generally taken from 
a 32x32 or 64x64 texture tliat’s tiled re¬ 
peatedly across the polygon, for several 
reasons— database size, amount of art¬ 
work, and performance (a 64x 64 texture 
sits nicely in the 486 or Pentium cache) . 
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RAMBLINGS IN REAL TIME 


The interpolated lighting can consist of 
eitlier a color intensity value or three sep¬ 
arate red, green, and blue values, RGB 
lighting produces more sophisticated re¬ 
sults, such as colored lights, but is slower 
and best suited to RGB modes. Games like 
Quake that are targeted at palettized 256- 
colOT modes generaDy use intensity light¬ 
ing; each pixel is lit by looking up the pix¬ 
el color in a table, using the texel color 
and the lighting intensity as the look-up 
indices. 

Gouiaud shading allows for decent light¬ 
ing effects with a relatively small amount 
of calc\iiation and a cx^mpact data set that's 
a simple extension of tlie basic polygon 
model However, there are several im¬ 
portant drawbacks to Gouraud shading. 

Problems with Gouraud Shading 

The quality of Gouraud sliading depends 
heavily on the average size of the poly¬ 
gons l>eing drawn. Linear interpolation is 
used, so highlights can only occur at ver¬ 
tices, and color gradients are nionotonic 
across die face of each polygon. This can 
make for bland lighting effects if polygons 



Figure 1: Adding an extra ifertex 
directly beneath a lighL (a) Wall is a 
single polygon before adding a light 
Lmiex,^ (b) wall becomes four polygom 
after adding a light tjertex directly 
^neatb a light. 


are large, and difficulty with spotlights and 
other detailed or dramatic lighting effects. 
After John brought the initial, primitive 
Quake engine up using Gouraud shading 
for lighting, the first diing he did to im¬ 
prove lighting quality was add a vertex to 
create new polygons wherever a spotlight 
was directly over a polygon; the new ver¬ 
tex is centered under the light, as in Fig¬ 
ure 1. This produced fairly attractive high¬ 
lights, but simultaneously made evident 
several problems. 

A primary problem with Gouraud sliad- 
ing is that it requires the vertices used for 
world geometry to serve as lighting sample 
points as well, even though iliere isn't nec¬ 
essarily a close relationship between light¬ 
ing and geometry. This artificial coupling 
often forces tlie subdivision of a single poly¬ 
gon into several polygons purely for light¬ 
ing reasons, as with the spotlights men¬ 
tioned earHen these extra polygons increase 
the world database size, and the extra trans¬ 
formations and projections that tliey induce 
can liann perfonnance considerably. 

Similar problems occur widi overlapping 
lights, and with .shadows, where addition¬ 
al polygons are required in order to ap¬ 
proximate lighting detail well. In particu¬ 
lar, good shadow edges need small 
polygons, otlierwise the gratiient between 
light and dark gets spread across too wide 
an area. Worse .still, the rate of ligliting 
change across a shadow edge can vary con¬ 
siderably as a function of the geometr>^ the 
edge crosses; wider polygons stretch and 
diffuse the transition between light and 
shadow. A related prol.ilem is tliai light¬ 
ing discontinuities can be very visible at 
t-junctioas (although ultimately we liad to 
add edges to eliminate t-junctions anyway, 
to stop dropouts along polygon edges). 
These problems can be eased by adding 
extra edges, but that increases the raster¬ 
ization load. 

Another problem Is tliat Crouraud shad¬ 
ing Isn't perspective correct. Witli Gouraud 
shading, lighting varies linearly across the 
face of a polygon, in equal increments per 
pixel— but unless the polygon is parallel 


to tlie screen, the same sort of perspec¬ 
tive correction is needed to step lighting 
across the polygon properly as is required 
for texture mapping, l^ck of perspective 
correction is not as visibly wrong for light¬ 
ing as it is for texture mapping, because 
smooth lighting gradients can tolerate con¬ 
siderably more warping tlian can tlie de¬ 
tailed bitmapped images used in texture 
mapping, but it nonetheless shows up in 
several ways. 

First, die extent of the mismatch between 
Gouraud sliading and perspective lighting 
varies with the angle and orientation of 
the polygon being lit. As a polygon turns 
to become more on edge, the lighting 
warps more and shifts relative to die per¬ 
spective texture-mapped texels it's shad¬ 
ing, an effea HI call “viewing variance.” 
Lighting can similarly shift as a result of 
clipping—for example, if one or more 
polygon edges are completely dipped; I'll 
refer to this as ^'clipping variance.” 

Tliese are fairly subtle effects; more pro¬ 
nounced is the rotational variance tliat oc¬ 
curs when Ckiuraud shading any polygon 
witli more tlian three vertices. Consistent 
lighting for a polygon is fully defined by 
three lighting values; taking four or more 
vertices and interpolating among tliem, as 
Gouraud shading does, is basically a hack 
and does not reflect any consistent un¬ 
derlying model. If you view a Gouraud- 
shaded quad head-on, then rotate it like 
a pin wheel, tlie lighting will sliift as the 
quad turns; see Figure 2. The extent of 
the lighting shift can be quite drastic, de¬ 
pending on how different llie colors at tlie 
vertices are. 

It was rotational variance that finally 
brought the lighting issue to a head for 
Quake. We'd look at the floors (which 
were Gouraud-shaded quads), then weYl 
pivot and the lighting would shift (espe¬ 
cially where there were spotlights and 
shadow.s). Given tlie goal of rendering the 
world as accurately and convincingly as 
possible, tlii.s was unacceptable. 

The obvious solution to rotational vari¬ 
ance is to use only triangles, but that 
brings with it a new set of problems. It 
Uikes twice a.s many triangle.s as quads to 
describe the same scene, increasing tiie 
size of the world database and requiring 
extra msterization at a performance cost. 
Triangles still don't provide perspective 
lighting; their Lighting is rotationally in¬ 
variant, but it's still wrong—just more 
consistently wrong. Gouraud-shaded tri¬ 
angles still result in odd liglvting patterns 
and require lots of triangles to support 
shadowing and otlier lighting detail. Fi¬ 
nally, triangles don't solve clipping or 
viewing variance. 

Yei another problem is that, while it 
may work well to add extra geometiy" so 



Figure 2: Gouraud shading lories uitb polygon screen oriefUation. (a) Rotated 0 
degrees; (h) rotated 90 degrees. 
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that spotlights and shadowys shtm^ up well, 
that's feasible only for static lighting. Dy¬ 
namic lighting— light cast by sources tliat 
move—has to work with whatever ge¬ 
ometry the world has to offer becau.se its 
needs are constantly changing. 

These issues led us to conclude that if 
we were going to use Gouraud shading, 
we would have to build levels from 
many small triangles, m\h geometry suffi¬ 
ciently detailed to support complex lighting 
so the inaccuracies of Gouraud shading 
wouldn't be too noticeable. Unfortunately, 
that line of tliinking brought us Ixack to die 
problem of a much laiger worid database 
and a much heavier rasterization bad (all 
the worse liecause Gouraud shading re¬ 
quires an additional interpolant, slewing die 
inner rasterization loop), so that not only 
would the world still be less than totally 
solid because of the limitations of Gouraud 
shading, but tiie engine would also lie too 
.slow to support the complex worlds we had 
hoped for in Quake^ 

The Quest for 
Alternative Lighting 

None of which is to say that Gouraud 
shading isn't useful in general. Descefil 
uses it to excellent effect, and in fact, 
Quake uses Gouraud shading for moving 
entities, because these consist of small tri¬ 
angles and are always in motion, which 
helps hide the relatively small ligliting er¬ 
rors. However, Gouraud shading didn’t 
seem capable of n^eting our design goals 
for rendering quality and speed for draw¬ 
ing the world as a whole, so it W'as time 
to look for alfernatives. 

There are many altemalive lighting ap¬ 
proaches, most of them higher quality ilian 
Gouraud, starting witli Phong shading (in 
which the surface normal is interpolated 
across the polygon’s surface) and going 
aU the way up to ray-tracing (in which full- 
illumination calculations are performed for 
all direct and reflected paths from each 
liglit source for each pixel). What all tliese 
approaches have in common Ls that they're 
slower than Gouraud shading—too slow' 
for our purposes in Qtmke^ For weeks, we 
kicked around and rejected various pos¬ 
sibilities and continued working with 
Gouraud shading for lack of a better al¬ 
ternative— until the day John came into 
work and said, "1 have an idea../ 

Decoupling Lighting 
from Rasterization 

John’s idea came to him while he was 
looking at a wall in Qwe?^that had been 
carved into several pieces because of a 
spotlight, with an ugly lighting glitch due 
to a t-junction. He thought to himself that 
if only there were some way to treat it as 
one surface, it would look better and draw 


The traditional 
way to do 
realistic lighting in 
polygon pipelines is 
Gouraud shading 


faster— and then he realized that there 
was a way to do tliat. 

The insiglit was to split lighting and ras¬ 
terization into separate steps. In a normal 
Gouraud-based msterizer, the first step is 
offline preprocessing when the world 
database is built. During this step, poly- 
goas are added to support additional light¬ 
ing detail as needed, and lighting values 
are calculated at the venices of all poly¬ 
gons. At run Lime, the lighting values are 
modified if dynamic lighting is required, 
and then the polygons are drawn with 
Gouraud shading. 

Quake's approach, which fll call 
“surface-based lighting,” preprocesses dif¬ 
ferently and adds an extra rendering step. 
During offline preprocessing, a grid (called 
a “light map”) is ailcuiated For each poly¬ 
gon in the world, with a ligliting value ev¬ 
ery 16 texels horizontally and vertically. 
This lighting is done by casting light from 
all the nearby lights in the world to each 
of the grid points on the polygon, and 
summing the results for each grid point. 
The Qtmke preprocessor filters the values, 
so shadow edges don’t have a stairstep 
appearance (a technique suggested by 
Billy Zelsnack); additional preprocessing 
could be done, such as using Phong sliach 
ing to make surfaces appear smoothly 
curved. Tlien, at run lime, the polygon's 
texture Is tiled into a buffer, witli each tex- 
et lit according to the weighted average 
intensities of die four nearest light-map 
points, as in Figure 3. If dynamic lighting 
is needed, the light map is modified ac¬ 
cordingly before the buffer, which I'll call 
a “surface," is built. Then the polygon is 
drawn with perspective-texture mapping, 
with die surface serving as the input tex¬ 
ture and with no lighting performed dur¬ 
ing the texture mapping. 

So what does surface-based lighting buy 
us? First, It provides consistent, perspective- 
correct lightmg, eliminating all rotational, 
viewing, and clipping variance, because 
lighting Ls done in surface space rather dian 
in screen space. By lighting in surface 


space, we hind die ligliting to the texels in 
an invariant way. Then die lighting gets a 
free ride through die perspective-texture 
mapper and ends up perfeedy matched to 
tlie texels. Surface-based ligliting also sup¬ 
ports good, altliough not perfect, detail for 
overlapping lights and shadows, Tlie 16- 
texel grid lias a resolution of two feet in 
the frame of reference, and diis rel¬ 

atively line resolution, togetlier with the fil¬ 
tering performed when die light map is 
built, is sufficient to supiiort complex .slmd- 
ows wdth smoothly fading edges. Addi¬ 
tionally, surface-based lighting eliminates 
lighting glitches at t-junctions, b^uuse light¬ 
ing Is unrelated to vertices. In short, sur¬ 
face-based lighting meets all of Quake’s 
visual quality goals, which leaves only one 
question: How' does it perlbrm? 


Size ond Speed 

As it turns out, die raw' speed of surface- 
based lighting is pretty good. Although an 
extra step is required to build the surface, 
moving lighting and tiling into a separate 
loop from texture mapping aliow.s each 
of the ioop.s to lie optimized very effec¬ 
tively, with almost all variables kept in 
registers. The surface-building inner loop 
is particularly efficient, because it consists 
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The lexlure is tiled acrose the surface, 
with each texel tit according to the 
weighted averages of the four nearest 
[jghE-map values. (The black dots on 
the surface show where the light-map 
points fall for illustrative purposes, 
and are not aciualljr drawn.) 
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Surface 


Figure 3: A surface is built b^' tiling the 
texture and lighting the t^els from the 
light map. 
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New Java Class Libraries!! 


Try our new object oriented Java class libraries: 
Objective Blend "and Objective Grid!! 



Objective Blend (pictured) includes over ten components: 


☆ 

Tabbed Window 

☆ 

Property Sheet 

☆ 

Tree Control 

☆ 

Mask Edit 

☆ 

Enhanced Combo 

☆ 

Enhanced List 

☆ 

Progress Indicator 

☆ 

Flexible buttons 

☆ 

Spinners 

☆ 

Meters and sliders 

☆ 

Font Chooser 

☆ 

And much more! 


Objective Grid is a 100% object oriented Java 
grid extension. The grid can easily be bound to 
any external data source including JDBC. 
Objective Grid also features multiple cell types, 
find/replace, undo/redo, covered cells, and an 
extensible control architecture. Be sure to try our 
demo to see all of the features! 


Both products include a 30-day money back guarantee, 60 
days of technical support, and FULL SOURCE CODE! 
Visual J-I-+, Cafe and Latte are supported. Objective Blend 
is $295 and Objective Grid is $395. Annual sub.scriptions 
are available for both. All major credit cards are accepted. 


Save a bundle: Objective Blend/Grid 
bundle is only $595. Order today! 


For FREE DEMOS Surf to: 


WWW.STINGSOFT.COM 


Stingray Software, Inc. 

1-800-924-4223 

Voice: (919) 933-0863 
Fax; (919)933^0892 
'’We add class lo Java!" Email: saIes@stingsoft.com 



RAMBLINGS IN REAL TIME 

of nothing more than interpolating inten¬ 
sity ^ combining it with a texel, using the 
result to locjk up a lit texe! cdor, and stor¬ 
ing the results with a dword write every 
four texels. In assembly language, weVe 
gotten this code down to 2.25 cycles per 
lit texel in Quake. Similarly, the texture- 
mapping inner Itxip, w^hich overlaps an 
FDrv for floating-point perspective cor¬ 
rection with int^er pixel drawing in 16- 
pixel bursts, has been .squeezed down to 
7.5 cycles per pixel on a Pentium, so tlie 
combined inner-loop times for building 
and drawing a surface is roughly in the 
neighl:)orhood of 10 cycles per pixel. It’s 
certainly possible to write a Gouraud- 
shaded perspective-correct texture map¬ 
per that's somewhat faster than 10 cycles, 
but 10 cycles/pixe! is fast enough to do 
40 frames/second at 640x400 on a Pen- 
tiumyiOO, so tlie cycle counts of surface- 
based lighting are acceptable. It’s worth 
noting that it’s possible to write a one- 
pass texture mapper that does approxi¬ 
mately perspective-correct lighting. How- 
ewer, 1 have yet lo hear of or devise such 
an inner loop that isn't complicated and 
full of special cases, which makes it hard 
to optimi^'e; worse, this approach dtxrsn’t 
work w'ell with the prtx^eduiul and post- 
proce.ssing techniques I’ll discuss shortly. 

Moreover, surface-based lighting tends 
to spend more of its time in inner loops, 
because polygons can have any number 
of sides and don’t need lo be split into 
multiple .smaller polygons for lighting 
purposes. This reduces the required 
amount of tnin.sformation and projection 
and makes polygon spans kjnger, So the 
performance of surface-based lighting 
stacks up very well indeed—except for 
caching. 

I mentioned earlier that a 64x64 tex¬ 
ture tile fits nicely in The processor cache. 
A typical surface dciesn't. Every texel in 
eveiy' surface Is unique, so even at 
320 x200 resolution, somelliing on the or¬ 
der of 64,000 texeis must be read in or¬ 
der to draw a single scene. This means 
that on a Pentium, we Ye guaranteed to 
miss the cache once e%^ery 52 texels, and 
the number can be consideralily worse 
than that if die texture-access patteras are 
such that we don't use every texel in a 
given cache line before that data gets 


o , Q. 
:Q q: 

Q • 
• Q 

• • 
• • 

Mipmap 
level 0 texels 

TTT^ 

O ^ • 

Corresponding 
mipmap 
level 1 texels 


Figure 4: Each texel at a givefi mipmap 
level corresponds to four texels at the 
preceding mipmap level 
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thrown out of the cache. Then, too, when 
a surface is built, die surface buffer won't 
be in the cache; so the writes will lie un¬ 
cached WTites that have to go to main 
memory', then gel read back from main 
memor>^ ai text Lire mapping time, poten¬ 
tially slowing things fuithen All this could 
have made the combination of surface 
building and unlit texmre mapping a po¬ 
tential perfomiance problem. 

Surface Caching 

When he thouglit of surlace-based light¬ 
ing, John immediately reali?:ed that sur¬ 
face building would be relatively expen¬ 
sive. (in fact, he assumed it would be 
more expensive than it turned out to be 
with hill assembly-language optimization.) 
His design included the concept of cach¬ 
ing surfaces, so that if the same surface 
were visible in die next frame, it could be 
reused without having to be rebuilt. 

With surface rebuilding needed only 
rarely, thanks to surface coaching. Quake' 
rasterization speed is generally the speed 
of the unlit, perspective-correct texture- 
mapping inner loop. And although that 
rasterization suffers from more cache miss¬ 
es than Gouraud-shaded, riled texture 
mapping, it doesn't have the overhead of 
Gouraud shading and it allows the use of 
larger polygons, in the worst case, where 
everyiJiing in a frame is a new surface, 
die .speed of die surface-caching approadi 
is somewhat slower than Gouraud shad¬ 
ing, but generally surface caching pro¬ 
vides equal or better perfonnance. Once 
surface caching was implemented in 
Quake, performance was no longer a 
problem—but became a concern. 

The amount of memory required for 
surface cadiing looked forbidding at first. 
Surfaces are large relative to texture tiles, 
because every texel of every surface is 
unique. Also, a surface can contain many 
texels relative to die number of pixels ac¬ 
tually drawn on die screen; due to per¬ 
spective foreshortening, distant polygons 
have only a few pixels relative to die sur¬ 
face size in texels. Surfaces associated widi 
paitly liidden polygons must be fully built, 
even though only part of the polygon is 
visible, and if polygons are drawn back 
to front wath overdraw, some polygons 
won’t even Ixj visible, but will still require 
surface building and cadiing. What ail diis 
meant was that the surface cache initial¬ 
ly looked very large, on die order of sev¬ 
eral megabytes, even at 320 x 200— too 
much for a game intended to run on an 
8 -MB machine. 

Mipmopping to the Rescue 

Two factors combined to solve this prol> 
lem. First, polygons are drawn di rough an 
edge list w idi no overdraw, a,s discussed 


The insight was to 
split lighting and 
rasterization into two 
separate steps 


a few columns hack, so no surface is ever 
built unless at least part of it is visible. 
Second, surfaces are built at four mipmap 
levels, depending on distance, with each 
mipmap level having one-quarter as many 
texels as the preceding level; see Figure 
4, Tlie mipmap level for a given surface 
is selected to result in a texel:pixel ratio 
approximately betw^een 1:1 and 1:2, so 
texels map rouglily to pixels, and more 
distant surfaces are correspondingly small¬ 
er. As a result, the number of surface tex¬ 
els required to draw^ a scene at 320x200 
is on the order of 64,000; the number is 
actually somew^fuit liigher (because of por¬ 
tions of surfaces that are obscured and 
views pace-tilted polygons, which have 
liigli texel-to-pixel ratios along one axis), 
hut not a whole lot highen Thanks to 
mipmapping and tine edge list, 600 KB has 
proven to be plenty for the surface cache 
at 320x200, even in the most complex 
scenes, and at 640x480, a little more than 
1 MB suffices. 

All mipmapped texture tiles are gener¬ 
ated as a preprocessing step and loaded 
from disk at run time, One interesting 
point is that a key to making mipmapping 
look good aimed out to be box-filtering 
down from one level to the next by av¬ 
eraging four adjacent pixels, then using 
error-diffusion dithering to generate tlie 
mipmapped texels, 

Also, mipmapping is done on a per- 
surface basis; the mipmap level for a 
whole surface is selected based on the 
distance from the viewer of the nearest 
vertex. Tliis led us to limit surface size 
to a maximum of 256x256. Otherwise, 
surfaces such as floors w^ould extend for 
thousands of texels, all at the mipmap 
level of die nearest vertex, and would re¬ 
quire huge amounts of surface cache 
space while displaying a great deal of 
aliasing in distant regions due to a high 
texel:pixel ratio. 

One final issue widi surface caching in- 
voK^es 3-D liardware accelerators. Surfiices 
are effectively large textures (and larger 
at the mipmap levels typically used at the 
high resolutions of accelerators than they 
are at 320x200), and texture memory 


tends to be a limited resource on accel¬ 
erators. Worse, accelerators are built for 
16 - or 32-bpp graphics, and surfaces are 
twice as large at l6-bpp as they are at 8- 
bpp and correspondingly slower tcj build. 
Although the edge list can still be used to 
cull invisible polygons, it's nonetheless 
true that a surface cache around 2 MB is 
best on a hardware accelerator. 

I'he first generation of accelerators was 
designed for 2 MB of RAM, which would 
have been a squeeze, but plummeting 
memory prices seem to liave solved the 
problem; 4 MB is fast Liecoming the stan¬ 
dard. And given sufficient memory, sur¬ 
face caching runs at about the same speed 
on accelerators as Gouraud shading (slow¬ 
er because of building and downloading 
surfaces, but faster because of fewer, larg¬ 
er fXJlygons), and still offers the same ad¬ 
vantage as in software: detailed and con¬ 
sistently correct lighting. 

Two Final Notes 
on Surface Caching 

Dynamic ligliting has a significant impact 
on the performance of surface caching, 
because whenever the lighting on a sur¬ 
face changes, the surface has to be re¬ 
built. In the worst case, where the light¬ 
ing changes on every visible surface, the 
surface cache provides no benefit, and 
rendering runs at tlie combined speed of 
surface building and texture mapping. Tills 
worst-case slowdown is tolerable but cer¬ 
tainly noticeable, so it’s best to design 
games that use surface caching so only 
some of the surfaces change lighting at 
any one time. If necessary, you could al¬ 
ternate surface relighting so that half of 
the surfaces change on ev^en frames, and 
half on odd frames, but large-scale, con¬ 
stant relighting is not surface caching’s 
strongest suit. 

Finally, Quake barely begins to tap sur¬ 
face caching's potential All sorts of pro¬ 
cedural texturing and postprocessing ef¬ 
fects are passible. If a wall is shot, a sprite 
of pcK’kmarks could be attached to tlie 
wall’s data structure, and the sprite could 
be drawm into the surface each time die 
surface is rebuilt. Tlie same could be done 
for splatters, or graffiti, with translucency 
easily .supported, Tlie.se effects would then 
be cached and drawm as part of the sur¬ 
face, so the performance cost would be 
much less than effects done by on-screen 
overdraw every frame. Basically, the sur¬ 
face is a iiandy repository^ for all sorts of 
effects. Multiple techniques can he com¬ 
posited because a surface caches tlie re¬ 
sults for reuse without rebuilding, and be¬ 
cause the texels constructed in a surface 
are automatically drawn in perspective, 
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Dr. Dobb’s CD-ROM Library 

Tlie Software ProfessDonaR's EssentDaR Resource. 
VDsDt our websRteE www.ddj.com/cdrom/ 


The Dr. Dobb's CD-ROM Library is an extensive collection of 
powerful tools and resources, essential to every programmer's 
productivity and success. The library focuses on critical aspects 
of programming ranging from an expansive back issue archive 
of Dr. Dobb's Journals to essential book selections on 


Algorithms and Data Structures and also Graphics 
Programming. And coming from Dr. Dobb's, you know that 
each CD-ROM is chock-full of source code. 

Take a moment and browse through our library. 

We guarantee your satisfaction. 




Featured Product of the Month 



W%ff/rb/e/ 


Essential Books on Graphics Programming CD-ROM 

• 7 of the most important books ever written on Graphics Programming 


Need to get up to speed on graphics 
programming-fast? There's only one 
definitive source you can turn to — 

Dr. Dobb's Essential Books on Graphics 
Programming CD-ROM! 

^ ” • Get seven of the most essential books on 

HAiIII graphics programming, with full text, diagrams, 

11^ * graphics, and source code-all on one CD-ROM. From 

fundamental algorithms to the most complex techniques, this CD-ROM 
lets you find all the critical information you need for your graphics 
programming projects. 

Texture mapping, color modeling, and morphing, all optimized for speedy 
2-D and 3-D graphics programming. Practical image acquisition and 
processing. High quality 3-D photorealistic graphics. 

Digital halftoning. Image synthesis and special effects. And much morel 
Plus, includes all source code supplied with the books. 


DDJ Editors'* choices: 

• Zen of Graphics Programming, by Michael Abrash 

• Practical Image Processing in C, by Craig A. Lindley 

• Photorealism and Ray Tracing in C, by Watkins, 
Coy, and Finlay 

• Applied Concepts in Microcomputer Graphics, 
by Bruce Artwick 

• Digital Halftoning, by Robert Ulichney 

• Digital Image Warping, by George Wolberg 

• Algorithms for Graphics and Image Processing, 
by Theo Pavlidis 


Price: $6$.3^ 


$62.96 





Dr. Dobb'sICD Release 4 

• Over 8 1/2 years (Jan. 1988 to Jun.1996) of Dr. Dobb's Journals and Sourcebooks 

• Includes every article, all the source code, and a super-fast search engine 


\ 


/ 


/ 


Trusted answers are hard to come by, but 
not with the Dr.Dobb's/CD! Whether it’s 
source code or detailed documentation 
on a specific subject— Dr. Dobb's/CD 

has what you need. 

Release 4 features all the articles and source code from 
Dr. Dobb's Journal from January 1988 through June 1996 
(over 8 1/2 years)... and also includes the Dr. Dobb's 
Sourcebook Series. 

Conduct full text searches with multiple keywords. Boolean 
logic, and wildcards .. quickly. You can copy and paste, 


export, and print directly from the CD-ROM. 
It’s the ultimate programming archive! 

Run your Dr. Dobb's/CD on 
either DOS or Windows. 


Put the programming 
expertise and innovation 
of today's best programmers 
at your fingertips. 


Price: $79.95 


Go to our website for more products from 
Dr. Dobb's CD-ROM Library: www.ddJ.com/cdrom/ 




Call: 

U.S. & Canada: 
800-992-0549 
All Other Countries: 
913-841-1631 
E-mail: orders@mfi.com 
Fax Orders: 913-841-2624 

Mail Orders 

Dr. Dobb's CD-ROM Library 
1601 West 23rd St. Ste. 200 
Lawrence, KS 66046-2700 USA 

















Buy 2 CDs and get 25% off the 3rd! 


Al Stevens Cram Course on C/C++ 

• A collection of 24 exciting developments in language technology 


\ 

\, 


Al Stevens, a world renowned 
programming expert and contributing 
editor for Dn Dobb*s Journal, has 
created the CD-ROM to answer all your 
CC+-f- programming questions - the 
Af Stevens Cram Course on C/C++. 

This CD-ROM includes the complete text of three books written 
by Al Stevens, an interactive step-by-step tutorial with precise 
explanations, video clips of Al discussing important topics, the 
GNU Compiler Suite directly connected to the exercises, lots of 
usable source code, plus a memory feature that bookmarks 
your place for quick returns to prior sessions. 

Use this CD-ROM on your programming projerts to answer 
questions, work through actual examples, compile your example 


source code, and make sure it's correct right then a 
No matter what your level of programming 
expertise, the A! Stevens Cram Course oti C/C++ 
will help you become a more proficient programmer. 

Includes these Books by AI Stevens; Welcome to 
Programming; Al Stevens Teaches C; Teach Yourself , 

This multimedia CD-ROM features: 

* Three Complete Programming Books 

* Bookmark for Quick Returns 

* Print and copy/paste functions 


I / 

.C++. 



/nteract/ve Tutorials 
Video dips 
BuHt in Compiler 


Designed for Win95 and 
NT (will work on 3,1) 


See screen shots and a more detailed 
explanation on our Website; 
wvtfw.ddj.com/cdrom7alstevens.htm 



Alternative Programming Languages CD-ROM, Volume 2.0 

• A collection of over 35 exciting developments in language technology 

Here's what you get... 


I 


/ 


\ 


Due to popular demand. Dr. Dobb's has col¬ 
lected another volume of programming lan¬ 
guages and tools. The editorial staff of Dr. 
Dobb's has once again assembled the most 
useful, interesting, and essential program¬ 
ming languages available and created The 
Alternative Programming Languages CD-ROM, Volume 2.0. This 
newest release contains over 35 programming languages, plus a 
large number of tools and utilities all on this one CD-ROM. 

Whether involved in object-oriented development, Internet 
development, text processing or document formatting, this 
definitive collection of languages and tools will help any serious 
programmer increase their productivity and reach that next level of 
programming excellence. ^ 




Java • Modula3 • Oberon 2 • SmeRtafk X • Sather 

• ErfW • Small Eiffel • H^ell^OFER • ML • J 
DSC • UC/C++ • Gltsh • StrandSS • Parasol • Phi (Phantom) • Codctail 

• Python • Td • Bob • Pert * Bob DLL • R^CX • Netreioc • Lout • 

Ghostscript • Slang • Uc • Gnu C • CSC • Moduta 2 • G77 • Pascal • 
Dylan • Forth • Neudl • Quincy • D’Flat • • And morel 

These powerful and Innovative languages come with source code for 
compilers or interpreters, enabling you to put this CD-ROM to work 
immediately on your programming projects. This Is truly the most 
extensive collection of programming languages ever assembled. 


Price: S49.95 



H Essential Books on Algorithms and Data Structures CD-ROM 

• 8 essential books selected by the Or Dohb's Editorial Staff 

Have you ever been stumped when ere- learn from the experts. Set up your algorithms 

ating an algorithm or data structure? first time — before you even write that first fin^ 

Then the Essent/a/Books on A/oodthms _ _ 

and Data Structures CD-ROM belongs on Your CD-ROM incudes these must-have feature 
your desktop! * ^ Powerful Full-Text Search Engine 

• Full Windows Functionality 

These eight books, selected by the Dr Dobb s editors are the ■ Hyperlinked TOCs and Indexes for each Book 

most important books ever written on the subject and provide ■ Create your own Bookmarks and Annotation: 

you, a software professional, with the details you need to sue- « p|ys much more! 

ceed. Plus, this CD-ROM features a full-text search engine, giv- 
ing instant access to the entire contents of all eight books. 


Price: $59.95 





Included on this CD-ROM: 

• Web Browsers 

• Graphic Conversion Utilities 


World Wide Web Toolkit CD-ROM 


• The ultimate collection of software resources for the World Wide Web 


' Graphic 
' Search Engines 


World Wide Web Toolkit CD-ROM is 
the most comprehensive compendium of 
software resources relating to all aspects 
the World Wide Web. 


• HTML Authoring Tools 

• Web Servers 
...Plus Much Morel 


Contains tools for all the major platforms uset 
including Unix, 16 & 32 bit Windows, Macintosh 
tools come with complete source code for C, C+ 
your own Web Browser to locate and download the tools 
a p p I i cat i o ns d i rectly from 


the CD-ROM. Save time 
and trouble^avoid hours 
of on-line time! 


Price: $29.95 


Go to our website for more products from 
Dr. Dobb's CD-ROM Library: www.ddj.com/cdrom/ 
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Take Control! 



I t wasn't long ago that most people 
thoLiglil OOP was the sound niatle by 
aijt(x>n characters when they were hit 
In tlie stomach. Back then, one of tlie 
best examples of an object-oriented lan¬ 
guage was Smalltalk. Around that time, a 
friend of mine walked into my office with 
a magazine advertisement for a popLilar 
Smalltalk product. Object-oriented pro¬ 
gramming will ckinge everything ” tie said. 
"Look at this. A whole text editor in three 
lines of code/' 

Of course, that was possible not be¬ 
cause of OOl^, but because tliat Smalltalk 
product came with a nice library that 
wrapped a Windows edit contrcjl. To write 
a text editor from scratch in Smalltalk 
would Ixf the usual nightmare, of course. 
The same is true of Visual Basic, A great 
deal of VB's ease of use derives fmm the 
selection of components tliat you can eiis- 
ily incorporate Into your programs. Mow- 
ever, what happens when you can't find 
a VB control to suit your needs? Should 
you create your own? 

i:)elplii alk)ws you to write new compo¬ 
nents easily using Delplii. Alas, tills Isn't true 
witli Vli. Instead, you must write ActiveX 
controls Cfomierly known as OCXs), and 
that typkuUy means using C or C++. In par- 
ticukir. Visual C++ has a C++ library (MFC) 
that greatly simplifies writing AaiveX con- 
m>is. You can write them from scratch or 
sulKlass existing Windows controls. 

Even if you have just a little experience 
with C++, you'll find it surprisingly easy 
to write your own custom controls. Cus¬ 
tom controls allow you to write code in 
C++ that might be difficult to wTite (or 
slow' to Rin) in VB. Also, you can distiibute 
your controls to other programmers w'lio 
might n(?t be able to duplicate your ef- 
forLs, Finally, creating a custom OCX con¬ 
trol is a handy w'ay to put your own code 
right on the VB palette for personal use. 

The basic steps required lor u,sing MFC 
to create an ActiveX control are simple. 
First, you run a special wizard to create a 
basic control. Tlie wizard automatically 


Alis a comulianl and author hiaed in the 
Houston area. His most recent hook is De¬ 
veloping ActiveX Web Controls (Coriolis 
Grtjup, 1996). You can find Al on the Web 
at http://ounmrld.compiiserw.com/bome- 
pageyAlfiWiUiams. 


Al Williams 


generates everything you need. If you 
build the project, you1l liave a generic, 
useless (but functioning) control. 

You'll want to add code to paint your 
contiol in a meaningful way. You'll also use 
a special tool. Class Wizard, to add prop“ 
erties, methrxls, and evenLs. In some cases, 
Class Wizard will w'rite al! tlie code for you. 
In otlier cases, you1l have to write code to 
produce the desired effect. In eitlier aise, 
Class Wizard will at least start yc^u off in die 
right place and keep everydiiiig in synch. 

Of course, you'll also use the normal 
MFC mechanisms to handle messages, 
dmw, and perform other munckine tasks. 
This is an advantage, unless you don't 
know MFC. Don't worry, though. The 
amount of MFC you need to know to 
write most controls is miniiiial compared 
to the amount of MFC you need ftjr a reg¬ 
ular application. If yoifve struggled witli 
docLiment/view architecture and other 
MFC oddities, you'll he happy to know 
y(ui don't need all tjf that for a control. 

Using Control Wizard 

To start your contiol , select New from the 
File menu. In the resulting diabg box, se¬ 
lect Pmject Workspac'e. This creates a new 
project with ks own makefile and sample 
.source files. Once you select Project 
Workspace, you’ll see an odd dialog box 
that has a vertical strip of icons on the left 
side (Figure 1). The icon you want to se¬ 
lect is the one labeled Control Wizard. 
You can select a project name and direc¬ 
tory u.sing the right side of die diabg. lYess 
the Create button to proceed. 

The Control Wiziird uses two dialogs to 
collect information (Figures 2 and 5). Tlie 
first dialog allows you to specify 

• How many controls you w'ant in your 
project. 

• If you want a mn-time license ( that is, 
if you want to support a mechanism tliat 
requires developers to have a key to de¬ 
sign with your control). 

• If you w'ant source-file comments. 

• If you w^ant skeletal help files. 

Once you press the Next button, tlie fi¬ 
nal dialog box w^ill appear (Figure 3) On 
this screen, you can edit tlie names of eiich 


class llie wizard wall create and change 
tile file name it will use for each class (usu¬ 
ally, you won't care). You c'^in also select 
among die lblk)wang options: 

• Tlie cootral may always activate when vis^ 
ible (some cx>ntaineis may ncjt allow iliis). 

• Tlie control may be invisible at mn lime 
(if die container allows this). 

• You may elect to have the control ap¬ 
pear in any ActiveX program's insert list 
(like any odier OLE-style document). 

• The wizard will create an About box, if 
you request it. 

• The ccmtrol can act as a simple frame 
conttiiner tliat am cxjniain otlier window;s. 

You can also elect to sulxlass a standard 
Wincktw s control (for exmnple, a button). 
'I his is usually not very useful, since VB al¬ 
ready provides ordinary controls. Mowev- 
er, k you have a caistom conu'ol you’d like 
to use in this option can lie useful. 

Code You Add 

Often, the only ccxie you'll direcily add to 
die files diat die Cbntrol Wizard generates 
is the OnDraw functicsn. This function 
paints tile ctintrol on a device context (DC). 
Instaid of a n( )rmal Wind<jws DC, this func¬ 
tion receives an MFC CDC. Tliis is just an 
fihject tliai encapsulates an ordinaty device 
context. The CDC has member functions 
tliat correspond to ordinaiy devic'e-context 
functions. Fcx exam pie, in Windcws you 
might WTite T(^iOut{dcfiX)/HeIp/'fiX wliile 
in MFC, you would write dc->Te:>ct- 
Chttfao/HelprfiJi. Since a CDC Is a C++ 
ohjecT, it automatically frees Itself when it 
goes out of scope, 'fherefore, you don't 
liave to call ReleaseDC or w orry alxiut die 
device context's dispasition. 

MFC calls when it needs to 

paint an active control or build a metifile 
for an inactive control. If you w^ant to sup¬ 
ply sep'arate code ft)r drawling the inactive 
contjol, you’ll need to override OnDrati>- 
Metafile. In either c’ase, you should realize 
tliiit an inactive conircil's device context is 
in an unknown state. You'll need to initial¬ 
ize an>tliing you use. It is also a grx>d idea 
to use SatJelJC to preserve die state of the 
DC so you can restore it liefore returning. 

On occasion, you might w^ant to add 
some custom code to the control's con¬ 
st nictor or destRictor. Howrever, to add 
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properties, metliods, and events, you’ll use 
Class Wizard to either write the code or 
to place stub functions in the code that 
you will finish writing. 

The other code you might add to a con¬ 
trol would handle ordinary window events. 
For example, a control that acts like a but¬ 
ton might accept mouse events. You use 
Class Wizard to handle these events. This 
Is exactly the same way dial you use Class 
Wizard in the usual MFC program. 

To handle a message in the control, 
start Class Wizard (you can press Con¬ 
trol+W or select it from the View menu 
or the toolbar). Make certain that the Mes¬ 
sage Map tab is active and that the con¬ 
trol object is selected (Figure 4). In the 
left-hand list box, make sure the object 
is selected, and not a menu ID. Next, .se¬ 
lect the message of interest in the right- 
hand list box. 

With the correct items selected, click 
on the Add Function button (you can also 
double click the message in the right-side 
list box). Tliis places a stub function in 
your code. If you want to immediately 
edit die code, just click on the Edit Code 
button. Make sure to select OK on the 
Class Wizard screen and not Cancel or 
Close. This ensures that the project re¬ 
tains your changes. 


New Pioiocl Woiktpacc 


Ii1» 


Adding Properties 

Properties are the heart and soul of Ac¬ 
tiveX controls. Adding them with Class 
Wizard couldn’t be easier. Simply start 
Class Wizard, and select the OLE Au¬ 
tomation tab, then press Add Property (see 
Figure 5). From here, you can select a 
stock property or name a new property. 
If you select a stock property, Class Wiz¬ 
ard automatically arranges to store it and 
provides a notification function you can 
override to detect when the property 
changes. For example, when the stock 
Text property changes, the framework will 
call OnTextChanged. You can retrieve the 
text as a BSTR (an ordinary BASIC string) 
by using the GetText function, or as a 
CString (a C++ string) by calling Interrial- 
GetText. You need only inform Class Wiz¬ 
ard that you want the stock property. 

When adding a custom property, you can 
selea between two types. The member-vari¬ 
able type allows you to define a member 
variable that corresponds to the property. 
If you like, you can also define a function 
that the framework will call when the prop¬ 
erty changes. Class 
Wizard automatically 
provides the variable 
and the notification 
function’s .skeleton. 


Your other choice for properties is to 
use get and set member functions. In this 
case, you specify a member function that 
the framework calls when a container sets 
the property (the set function) and another 
function that supplies the value of the 
property (the get member function). You 
don’t need to supply both functions if you 
want a read-only or write-only property. 

When you create a member function 
property, Class Wizard automatically cre¬ 
ates skeleton functions for you. The get 
function returns a value that has the same 
type as the property. The set function uikes 
a value as an aigument. You can also make 
pseudoarray properties by providing ad¬ 
ditional aiguments to the get/set members. 
What you do with these functions (and 
any extra arguments) is up to you. If you 
ne^ a variable to store the property, you’ll 
have to define it manually. 

By default, stock properties are persis¬ 
tent That is, the container saves them when 
it .saves the control, and MFC arranges to 
load thcTn back in when the cx)ntainer loads 
(continued on page 54) 
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Figure 1: Starting a new ActiveX control. 
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Figure J; The second Wizard dialog. 
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Figure 2: The first Wizard dialog. 

Dr. Dobh^s Sourcebook, ISovemberlDecember 1996 


Figure 4: Class Wizard's message map screen. 
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(continued from page 51) 
the contrd. if you want any custom prop¬ 
erties to be persistent, you need to add a 
special PX_ function to the DoPropEx- 
change function. Hiese functions (one for 
each common type) take the name of the 
property, the corresponding variable in 
your code, and a default value as argu¬ 
ments. Of course, some run-time proper¬ 
ties may not require persistence, in which 

Ambient Property Functions 

AmbientAppearance 

AmbientBackColor 

AmbientDi splay Name 

AmbientFont 

AmbrentForeColor 

AmbientLocalelD 

AmbientScale Units 

AmbientTextAlign 

AmbientUserMode 

AmbientUIDead 

Ambients howG nabH andles 

AmbientShowHatching 

Table 1: MFCfunctions to retrieve 
common ambient properties. 


case, you don't need to take any special 
action in the DoPropExcbange function. 

Using Ambient Properties 

You don't define ambient properties in your 
code. These are properties the cxDntainer 
supplies to the control. You may use them, 
but controls don't define them. MFC pro¬ 
vides simple functions to retrieve common 
ambient properties (Table 1). You can also 
get any arbitrary ambient property by call¬ 
ing GetAmhientProperty. Of course, dien 
you need to know the property's DISPED— 
a unique ID that identifies each property. 

Adding Methods 

When you want to add a method, simply 
select die Add Mediod button from Class 
Wizard’s OLE Automation tab. Tliis brings 
up a dialog you can use to create methods 
(Figure 6). Each method c:an have up to 
16 parameters. Once Class Wizard creates 
a stub, you can fill in die appropriate code. 

Adding Events 

Class Wizard makes 
adding events trivial. 
Select die OLE Events 
tabs. Just name the 
event (or select a 
stock event name). 
Events can have up to 
15 arguments diat you 
specify near die bot¬ 
tom of the dialog (Fig¬ 
ure 7). 

Class Wizard auto¬ 
matically writes a 
complete function 
that will trigger the 
event (the function 
will sLirt widi Fire, as 
in FireClick). You 
don't need to take 


any further action. When you want to fire 
the event, just call this firing function. Of 
course, you have to pass any arguments 
specified when you created die event. 

The default MFC code will fire some 
stock events by default. For example, 
when the control detects a character (a 
WM_CHAE. message), it calls FireKeyPress 
unless you override the message 

and don't call the base class. You’ll find a 
list of window messages that MFC con¬ 
verts to events in Table 2. 

Adding Property Sheets 

MFC makes it easy to add property sheets. 
However, since VB uses an integral prop¬ 
erty brtjwser, you don’t have to add a prop¬ 
erty sheet to a control that you plan to use 
with VB. You can find more information 
abcjut property sheets in the online help. 

More Sophisticated Additions 

MFC uses the COIeControl class to repre¬ 
sent all ActiveX controls. You can find a 
wealdi of functions in diis base class that 
you can override to handle certain con¬ 
ditions. For example, if you want to know 
when ambient properties change, you can 
override OnAmbientProperiyCbange. If 
you want to know when die container will 
ignore events, override OnFreezeFtJents. 

Testing and Using the Control 

You am embed an MFC contrd in any ap¬ 
propriate container. However, you may find 
it especially useful to use the test contain¬ 
er that comes with the Visual C++ tools. 
This container (Figure 8) allows you to em¬ 
bed any control in it. Tlien you can ex¬ 
amine its properties, monitor its events, and 
set conditions like ambient properties. 

To insert your control in the test con¬ 
tainer, you'll need to nm TSTCON32.EXE 
(u.sually available on the Tools menu of 



Figure 5' Adding a property . 




Figure 1: Adding an ei^nt. 


Figure 6: Adding a method. 
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the Visual €+■*■ menu). Then, select the 
Edit menu’s Insert Control item. You can 
use items on the Edit, View, and Options 
menus to exercise and monitor the con¬ 
trol. In particular, you can use the event- 
bg window (found on the View menu) to 
monitor events tliat the control fires. 

If you want to use your amirol with VB, 
you have to add it to the tool palette by in¬ 
voking the Custom Control cT)mmand from 
the Tools menu. Once it’s on llie palette, 
you can use it like any other VB control. 

Youil find a complete ActiveX control 
example in the online listings. You’ll see 
it is quite straightforward. Class Wizard 
adds all of the prop)erties, nr»ethods, and 
events. The only code that I manually 
wrote is in the OnDraw function. 

Subclassing A Custom Control 

Although the Q)ntroI Wizard will help you 
subclass built-in Windows controls, you 
won’t often use tliis feature. VB already sup¬ 
plies most ordinary controls and you can 
only select the built-in controls from the 
list. However, wliat alxxit custom controls 
that might already exist as C or C++ DLLs? 

In truth, any ordinary Windows control 
can become an ActiveX control via sub¬ 
classing. The only requirement is that the 
control must be able to paint itself to an 
arbitrary device context. Tliere was an un¬ 
documented feature in many old-style con¬ 
trols that allowed for this. If you send an 
ordinary control a WM_PAINT message, 
but set the wParam parameter to an HIX, 
the control would paint to that device con¬ 


text instead of using the usual BeginPaint 
call to obtain an HDC. 

MicTOsoft never officially documented 
this anywhere (although several MFC sam¬ 
ples relied on this fact). With Windows 
95, however, there is an official way to 
ask a control to paint to a specific device 
context. This Ls the WM_PRINT message. 
WM_PRINT takes the HDC in its wParam 
argument, and a function code in the 
IParam argument. MFC can use either of 
these meiliods to force the control to paint 
to a metafile. This metafile becomes the 
presentation for the subclassed control 
when it is in the inactive state. 

If you need to work with a CTJstom con¬ 
trol, you’ll have to make sure it supports 
these painting features. If not, you may 
have to do a good bit of work to draw the 
control. If you have the .source ccxJe for 
the control, it may be a very simple mod¬ 
ification to make the contrcJ aware of this 
protoctJ. For example, suppose ycxir con¬ 
trol’s source had a section of code that 
kx)ked like Example 1(a). It would be .sim¬ 
ple to cliange it to look like Example Kb). 

Note that this does not provide a full 
implementation of the WM_PRINT com¬ 
mand, but it is adequate, at least for cTeat- 
ing an ActiveX control. Also, this cxxle as¬ 
sumes you don’t ase any of the information 
out of the PAINTSTRUCT (like the rectan¬ 
gle to redraw). This Ls 
often the case. If it 
isn’t, you’ll have to 
come up with .suit¬ 
able fake values for 


the PAINTSTRUCT when wParam is not 
NULL. Usually, this means using the client 
rectangle for the bounding box and ap¬ 
propriate defaults for the flags. 

A Custom Control 

Listing One (listings l^gin on page 57) Is 
a simple control written in C. (The com¬ 
plete package is available electronically; 
see “Programmer’s Servic'es," page 3 ) This 
control creates a countdown timer not un¬ 
like the one you .see on movie reels (you 
know— that stuff we used back before 
videotape). The DLL registers a custom 
window class, and that class implements 
the countdown timer. Notice that the timer 
may not be accurate in certain situations. 
If the .sy.stem is slow, the timer will count 
down every time it receives a WM_nMER 
message. This may cau.se the timer to 
count more slowly than it would if it act¬ 
ed corrcxlly, but it does allow the user to 
see the entire time elapse. 

The protocol for using the timer is a 
combination of Windows me.ssages and 
window extra words. You’ll find .several 
mes.sage.s and coastanLs in Listing Two. In 
addition to the messages, you can set the 
control’s background color by manipulat¬ 
ing its extra window bytes starting at off¬ 
set 8. The DWORD at this address sets the 
color in the usual RGB format. You c'an 


Message to Parent 

Reflected Control 

Message 

WM COMMAND 

OCM COMMAND 

WM CTLCOLOR* 

OCM CTLCOLOR 

WM DRAWITEM 

OCM DRAWITEM 

WM MEASUREITEM 

OCM MEASUREITEM 

WM DELETEfTEM 

OCM DELETEfTEM 

WM VKEYTOrfEM 

OCM VKEYTOITEM 

WM CHARTOITEM 

OCM CHARTOITEM 

WM COMPAREITEM 

OCM COMPAREITEM 

WM HSCROLL 

OCM HSCROLL 

WM VSCROLL 

OCM VSCROLL 

WM NOTIFY 

OCM NOTIFY 

WM PARENTNOTIFY 

OCM PARENTNOTIFY 


Message 

Event 

WM KEYUP 

RreKeyUp 

WM KEYDOWN 

FireKeyDown 

WM CHAR 

FireKeyPress 

WM 7BUTTONDOWN 

FireMouseDown 

WM 7BUTT0NUP 

RreMouseUp 

WM 7BUTTONDOWN 

FireClick 

WM MOUSEMOVE 

RreMouseMove 


Table 2: Automatic events. Table JL* Window message reflection (*MFC reflects this for 



Figure 8: Test container. 


Figure 9: Countdoum control. 
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(a) 

case WK.FAINT: 

dc=BeginPaint(hWnd,Sps ); 

EndPaiiit(hWnd*&ps) i 

(b) 

case W«_PAlNTi 
case WM_PRINT: 
if (fwPataiii) 

dc^BeginPaint(hWnd,&ps ); 
else 

dc=CEffiC)vParam: 

if (IwParaM) 

EndPaint(hWnd,&pB); 


Example Jf: Using MFC to change the 
code in (a) to (h). 

use SetWindowLong and GetWindoii^Long 
to read or ehange the value. 

When you want to set the timer to a spe¬ 
cific numtx^r of seconds, use the TC_SET 
message (place the number of seconds in 
wPamm), The TC_GETT1ME message re¬ 
turns the currenc number of seconds. To 
start or stop the timer, send a TC_GO mes¬ 
sage, If the wParam parameter is 1, the 
timer starts. If it is 0, the tbiier stops. 

Wlien each second elapses (wliich may 
not lie a true .second), the timer sends a 
WM_CONTOOL message witli the TCjnCS 
notificadcxi code in the liigli part wPamm 
The current time count is in iParam. When 
the count reaches zero, die period is com^ 
plete and the timer automatically stops. 

To use the conm>l in a C or G++ pro¬ 
gram, you can bad its DLL using die Load- 
Library call. Alternately, you can link with 
the corresponding IMPLIB. The dummy 
funaion TControi_InU providers you with 
a function to call so die linker will include 
the DLL if you elect to use die latter meduxL 

You’ll notice in the source ccxle diat tliis 
control properly handles WM^PAIKL and 
WM_PRINT. However, if it didn’t (and, in 
fact, it originally did not), it would fie triv¬ 
ial to change die code. 

So how can you use this control from 
Visual Basic? You can form an ActiveX 
control that subclasses the timer, and UsSe 
it as you would any ActiveX conlroL 

Subclassing the Control 

Although Control Wiziird won’t directly al¬ 
low us to subclass a custom control, we 


can ask it to subclass a standard control 
and make changes. 1 usually choase to 
subclass from a ^AT!C on the theoiy that 
this should be innocuous, but it doesn't 
seem to make any real difference. There 
are nine steps you1l need to take after you 
generate a standard subclassed control. 

1. Add the TCONTROL.H file to the con¬ 
trol’s CPP file. 

2. Find the name of the subclass in the 
PreCreateWifidow method and change 
it to reflea the custom control’s name. 

3. Load the library (or make the dummy 
caD to load the library) in the applica¬ 
tion’s Initinstance member. 

4. Add properties (use Cla.ss Wizard). 

5. Add PX_ funaions to implement per¬ 
sistent properties. 

6. Add methods (use Class Wizard). 

7. Add events (use Class Wizard). 

8. Add message-map entries and message 
functions to tire events. 

9. Modify tlie property page, if desired. 

For this contiol, 1 decided to implement 
a Count property tliat corresponds to the 
current count, Go and Stop methods, and 
a Tick event that fires with the TC_TICK 
message. You can find the results in List¬ 
ing Three, 

iliere are two major twi.sLs to sulx:kss- 
ing a control like this. First, MFC doesn’t 
CTeate the window until the first call to On- 
UrauK Thai means you can’t do anything 
tJiat lequires a window handle (for exam¬ 
ple, send messages) unliJ after tliat point. 

Tlie otiier issue Ls tiiat the TC_TrCK no¬ 
tification goes to die controis }iarent win¬ 
dow, not the c'tintrd itseE "Ihs poses a prob¬ 
lem, since you need to handle the TCjnCK 
notification in tiie COkContrvl-ik^nved dass 
dial represents the control, not in some dass 
diat represents the paient window. 

Luckily, the solutions to these problems 
are straightforward. Refrain from sending 
messages or uiherwise mardpulating the 
window during DoPropExchange, OnRe- 
setState^ or any other time when the win¬ 
dow may not be valid. Instead, rememlier 
the state of die control and initialize it dur¬ 
ing WM_CREATE processing. You can use 
Class Wizard to handle WM_CREATE, Nat¬ 
ural ly, when WM_CREATE occurs, the 
window will lie valid. 


Listing One 

^include Ctfdndorvs.h^ 

#Include <etdlib.h> 

IfibcludE '‘tcon'trOl, h" 

EAHDLE tilnst; 

/t Dumy entry point tij fcrce DLL load */ 

_declspec(dllexport) void FM PASCAL TControl.,lnit(voLd) 

I 

} 

LQWG PAR PASCAL ControlPtoc {HWKD v.UlNT cmd. 

WFARAM vFsraiD.LFARAM iFaran] 

I 


switch tcHd^ 

C 

case UM_PA 1 WT: 
case WM_PRINT: 
t 

EECT r.cct: 

iilt iL.yj 

iut tlck.aMt: 
char tkp [ 5 }t 
NDC dc; 

NMUSH hr.old.backr 
PAINraTRUCT ps: 

Lf {IvParaq) 


The notification problem is even sim¬ 
pler. MFC arranges to reflect certain mes¬ 
sages (including WM_COMMAND) from 
the parent window to the control window. 
When the parent window receives a 
WM^COMMAND, it reflects an OCM_ 
COMMANT^ message to the control. You 
can handle this with an ON^MESSAGE 
message map entry (although Class Wiz¬ 
ard wQl not make it for you). The Control 
Wizard automaticady sets this up for you 
in the case of WM_COMMAND, 

There are several other messages chat 
MFC reflects (Table 3). You can handle 
these using ON_MESSAGE in a fashion 
similar to the OCM_COMMAND sciution. 

The Count property requires special 
handling since tlie window is not valid un¬ 
til die first paint operation oocuis. The spe¬ 
cial variable mjeount holds a local counter 
that the control object maintains in the usu¬ 
al way. Then, during WM_CR£ATE pro¬ 
cessing, the ccxle sends the TC_SET mes¬ 
sage to the control to synchronize the 
control olijeci’s property with the real val¬ 
ue in die custom oontrd. 

Using the Control 

Once die control is working, it operates 
like any other ActiveX control (Figure 9)- 
If you plan to ship a subclassed control, 
however, be aware that you liave to ship 
liodi tlie control and die I.^LL tliat contains 
die original conool. (Assuming you have 
the right to distribute that DLL, of course.) 

When you install your files on a differ¬ 
ent machine, you must be sure that the 
custom control’s DLL resides where the 
AaiveX control can find it. Tlie standard 
SYS'ITM directory Is often a good choice. 
Without access to the base controLs DLL, 
any attempts to use the ActiveX control 
will fail, 

Olher Places 

Don’t forget: AaiveX controls are not just 
for VB. You can use them in Visual C++, 
Delphi, and many other places as well. 
Perhaps the most exciting use for them is 
to provide active content for web pages 
The latest Internet browsers can accept 
ActiveX controls using the <OBJECT> 
HTML tag. 

DDJ 
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dc-Beg.inF«ifiti(w.$pd): 

I 

d:e==fHEiC)wParam: 

SaveDCfdc); 

5 

br=Creai:iSolldBrush(RGB(fibtFF.0 }: 

back=C]:eBteSDlidBruah [GettfindouLong (v, EAC£) I; 
SeLHapMod 0 {(ic,KM_ISOTROFIC); 

GetClientRect (if, ir): 

SetWindfiwEKtEx(dc,20,2®.SULLJ i 

SetVievpartEttEt {dc, r. ^ ."bottoB, HULL); 

ticlt"G 0 tVindowLong(w, TICK}; 
amt=G«tWixidwLongfw,TIMELEFT:): 
old^SelactObjecttdc^back); 
fatblt tdq-0*0.20►20.PATCOPY); 
il Ellipseidc,0,0*20,20): 

/• Select new brush ♦/ 

SelfictObjectCdc.br); 
switch (tich) 
t 

case 0: 
iM0: 

y=0: 
break: 
caae 1 t 
xMS: 
y-2i 
break; 
caffe 2t 
311^20: 
y=10: 
break: 
case 3.E 
x'15: 
y=lS: 
break: 
case 4t 
ji=l0: 

y=20s 

break; 

ceae 5t 

: 

y=ia; 
break; 
caffe 5: 

i£:=0: 

y=J0: 
break; 
caae 7; 

K=5i 

y=2: 

break: 

} 

If (tick==B) 

Kllip0e(dt,0.0,2O.20): 

dee 

if (!PiBtdc,O*0.20,20,Jt,y*10.0)) MesflaBeBeep{(urNT5-t): 
SelectObjact[devoid); 

OeleteObjeCt(br); 

DeleteObJeet(back); 

/• Write text */ 

ret.t op“rc t.1eft^O; 
ret * rlEbt=rct * bottcui^ifl; 

Itoa (amt, tmp ,10): 

SetakMDde(dc.raANSPAREST): 

DrayText (dc, tmp, -1, bret, 

DT.CEKTERlDr.VCEKIERSDT.SrHGLELIHE); 
if (WFarsm) 

EndPaijit (.w. &pfi); 

ell a 

EjestoraDG(dc,-l) t 

return 0; 

) 

case V?M..TIMER; /* Do tidier stuff */ 

{ 

int tick.aBt; 

HWHD pareiit=GetParent (w); 
tick=6etWindowLong(w,TICK); 
if (++tick^9') 
t 

tieJt-0: 

aiit=GetVijidovLong(v,TIM£i.Err): 

Set WifldowLoQg (y, T THRT.KP T, - - amt); 

Po scMe E sage (parent *¥K_C0MaAND. MAKEUJHG (0 *TC_TICK)»ant); 
If tlamt) 

[ 

KillTlaerCw*!): 

) 

] 

SetWindGvLong(v,TlUR,tick): 

InvalidHteRectiw.MULL,FALSE); 
return 0: 

1 

case TC_SET: 

Set0iiidowLoug(w.TIMELEFT,yFaram] ; 

SetWindowLong(¥,TICK,0) ; 

Inval IdateRj&tt (w, MULL, FALSE); 
return 0; 
case T'C-GcrrtlME i 

return G«tWindoi^ongi[w,TlMLlET) i 
esse TC_G0t 
If (vfaram) 

SetTimfit[«*l,125*HD(LL); /* l/fltb second •/ 
else 

KillTieifir (w.l): 

return 0; 

] 

return DefWindowP roc fw. emd.vPsrem. iparaei): 

} 


/♦ Regiflter our class or unreglater it •/ 

BOOL WINAPI DllHa.ii](SAKDLE .hlnat .ULOKG reason *LFV0in na) 
{ 

WHDCU^SS VC' 

if (rtafiou=^DLL. PROCESSJkTTACH) 

( 

|iXoat=_hltiflt: 

¥C. IpszClaasNffse^IHECniU.: 
wc .hlnatai3ce“lillist; 

we, fftyle=CS_GLiO'0ALCLASS: 

wu - Ipf ELWndPcoc^ControiProc; 

we.hbrbacItground^EHBRdSfl) (COLOft.WINDOW+l); 

Wt-hCur&Qtr^LofldCtirsor (NULL, II>C_ARRCi¥); 

wc.hlcon-NUlL; 

vC, lpazMEmiMsfiie=MIIiL; 

wc.cbClBExtra=Oi 

wq -cbWndEitta=12: 

if rfRegiaterClassCfiiwc)) return FALSE: 

1 

if (ceaaon^LL_FROCESS_tlKTAmi) 
UnreB,laterClflas(riIIEtnBL,hInBt) ; 
return TRUE; 

1 


listing Two 

tdefine TIHECrrSL "TiaeCtrl" 

Nefine TC_SIT (WM.tlSER) 

H define TC.GO (VrM_aSER+l) 
tdeflne TC,TICK (¥K_0SER+2) 

Mefine TC.GEtTlME {UK_USER+2) 

Ideflne TIHELEFT 0 
4define TICK 4 
ltdefine BACK 8 

__declffpecrdlli-parts void FAR PASCAL TCantrol_Init(vold): 


Listing Three 

// couiitdn*cpp : lapleiBpfiration of CCountdnApp and DLL regietratiqn. 

linelude ’’atdafi*b'’ 
iinclude *qQnntdn*h“ 

lifdef _DEmiG 

#define new DEBUG.NEW 

tuudef THIS^J'ILE 

static char THIS_FILE[J = _FILE__; 

#Biidlf 


CCountdnApp HEAR tbsApp: 

coaet GUin CDECL BASED..C0DE _tlid = ( 0xa7e2ft560, 0ie«i4* 0iil.c£* ( 0ita7 * 0Kb2. 

0x44, 0x45* 0x53, 0x54, 0. 0 } 1: 

conat MOED _w\ferMaJor = 1; 
ccinfit WORD ^WlTerMiMr = 0; 

//////////////////////////////////////////////////////////////////////////// 

// CCountdnApp * *Initlnatanue - DLL initialization 


BfX^L CCountdnApp; :Initlnstenc«(} 

[ 

m=Loadlibrary("TCONTROL,DLL‘') j 
if (Idll) return FALSE: 

BOOL blnit ^ C01eContcoIHodule::InitInKtance(); 
If (blnit) 

[ 

) 

rattim blnit; 

// CCountdnAppt :£xitl!fistaDce - DLL teminatiun 


int CCountdnApp:;ExitlUEtance() 

C 

int nr; 

rv^^leCnatrolKodule; :EritInstanca() ; 

// if (dll) FreeLibrairy (dll): 

return nr; 

///////////////////////////////////////////////////////////////////////////// 
// DllilaaisterSarver - Adds entcies to the ayatem registry 
STDAFI Dl 1 RegieterSe ever (iraid) 

[ 

AP3t_M«lAE^_STATE t-flfxMnduI eAddrThia) t 

if ([AfxOleRegisterTypeLibCAfxGetlnEtsnceiRandleO , -tlid)) 
return ReeultFrc™SeoEie{Sll*FREG_E_TYPELIB) j 
if 11 COleObj ectFactojryfx:; Updatdteg IstryAll (TRUE)) 

rettiru ReaultfroiaScode(S^JEEt^_E_CLASS); 
raturn MJERROR; 

///////////////////////////////////////////////////////////////////////////// 
// DllUnregiatetServer - Remaves entries froB the system registry 
STDAPI DUUnraglaterServeiiveid) 

E 

AFK_MANAUE_ STATE r_afxlt(?duieAddrThi&) ; 
if (1AflOleUnrugis terTypaLib[„tlid)) 

return ResultFroraScbduCSELFREG.E.TYPELIB): 
if ( \ COIeObjectFaotoryEx;:UpdateRegistryAll(FALSE)) 
return HesultFTomScode(SELFRlG_E_CLASS): 
retnm HOERROR; 

} 


End Listings 


Dr. Dobbs Sourcebook, NovemherfDecember 1996 


57 





DTACK REVISITED 


The Promise and 
Reality of SMP 



I have had this experience exactly once, 
t was driving on a four-lane avenue 
just nortli of tiighway 101, in die itiid* 
die of Silicon Valley, at the peak of the 
morning njsh hour. 1 suddenly realized 
that 1 was alone. Wliether I looked for¬ 
ward, to die right, left, or in die rear-view 
tnirrors, there was no sign of life in sight. 
No people. Worse than that, diere was no 
traffic. And I was wide awake and com^ 
pletely solxrr! It was like being on the set 
of a science fiction movie: I expected a 
giant Mantis to stride into sight any mo¬ 
ment. 1 actually pulled to tlie side of the 
road and stopped. After about a half- 
miniile, one lone car appeared and piissed 
me. Whew! 

It was early August, 1989. Td been 
working for a year-and-a-half at Vicom, 
then one of four companies in the busi¬ 
ness of making general-purpose image- 
processing computers in die SlOOK-and- 
up price range. Vicom had shamk by 33 
percent during the rime I worked diere, 
and it had less diari a third of the em¬ 
ployees it had at its peak (and the indus- 
tiy^'s peak) in 1984. Every Friday at 5:30 
p.m., Pliiladelphia time, a Mayfield Fund 
representative would electronically deposit 
enougli money for Vicom's payroll, and 
die pay checks would lie handed out at 
Vicom in San )o.se. 

You see, Vicom was all but legally 
bankrupt. It had numerous bills out¬ 
standing for over six months. As is usual, 
a creditors’ committee was w'aiching for 


Hal is a hardware engineer who some¬ 
times programs. He is the former editor of 
DTACK Grounded, and can be contact¬ 
ed at balwb@ddj,com. 


Hal W. Hardenbergh 


an opportuniiy to force Vicom into Chap¬ 
ter 11 so diey could recover a few cents 
on the dollar. But they couldn't do that 
until Vicom had some assets, and Vicom 
had long since sold all its equipment, in¬ 
cluding the file cabinets, and leased them 
back. Vicom had no assets, so the credi¬ 
tors didn't file; they wouldn't even have 
recovered court costs. 

What happened to Vicom is what w'as 
liappening to the entire uiiage-processing 
industry, or at least the part that made 
general-purpose image-processing com¬ 
puters. The desktop personal computer 
was eating away at the base of the mar¬ 
keting pyramid that supported tlie indus¬ 
try. I knew w hat was going on as it was 
liappening, in some ways belter than niy 
bosses at Vicom. I liad personally partic¬ 
ipated in the general-purpose CAL> (Com¬ 
puter Aided Design) indastry and watched 
as the desktop personal computer ate that 
industry alive, too! I Would you believe a 
CAD computer used to cost S250K and 
up?) And I had run my own small com¬ 
pany for 14 yeai^, so I understood the fi¬ 
nancial nuances. 

Vicom's boss persuaded die Mayfield 
Fund that Vicom was too small, so Vi¬ 
com bought up Gould IGD (Image and 
Graphics Division) in Fremont, Califor¬ 
nia, and bought the image-processing di¬ 
vision of a little company in San Lean¬ 
dro, CA, called Pixan (The part of Pixar 
that remained behind later produced Toy 
Story.) But Gould IGD had 125 employ¬ 
ees in Fremont, and Vicom was moving 
to the Gould plant in Fremont. I decid¬ 


ed I didn't want to commute on the long, 
narrow parking lot locally known as In¬ 
terstate 880. 

So I was on my w'liy to a job inter¬ 
view. Just before 8:00 a.in., I had driv¬ 
en north on Lafayette Street and made 
the cloverleaf turn onto Tasman Drive 
heading toward.s Great America Park¬ 
way. Apparently Tasman, between 
Lafayette and Great America, w^as not a 
major traffic artery even during the morn¬ 
ing commute. 

Sfartyp Number Three 

S3 (short for “Startup ^3”), a spinoff of 
Chips & Technology, was led by one of 
C&Ts founders. The company was in its 
initial startup mode and liad rented space 
in a two-stoiy office building at the cor¬ 
ner of Tasm;m and Great America. I didn't 
know what product they were develop¬ 
ing, bu! a ct^lleague recommended I ap¬ 
ply there for a job; he had worked with 
S3's founder. 

Having just moments before had an ex¬ 
perience dial surely is simitar to an LSD 
rush, 1 arrived at that building and dis¬ 
covered it k)oked exactly like a motel, I 
had lived in a motel in Sunnyvale for al¬ 
most lour months lx;fore landing the Vi- 
cotn job. five never liked motels. I thought 
about the situation briefly and left, even¬ 
tually going to work for anodier image- 
processing company. Ifs a veiy^ good thing 
I ncfvcT applied for that job because (con¬ 
tinuing the SciFi inetaplior) I might have 
disappeared in a nuclear explosion. 

1989 SMP Market: 17 Units 

You see, S3 was founded to make an 
enormous amount of money by making 
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a motherboard chipset that would sup¬ 
port up to four x86 CPUs. Yep, S3 was 
going to ride the SMP (symmetrical multi¬ 
processing) market to fame and fortune. 

1 had definite ideas about the SMP mar¬ 
ket. One was that there was an annual 
demand for about 17 SMP computers. 
And Pve never been bashful about ex¬ 
pressing my opinions. 

C&T had discovered what the spinoff 
was up to and, naturally, started develop¬ 
ing its own x86 SMP motherlxiard chipset 
called ‘WAX.” S3 discovered tiie insanity 
of its business plan before actually plac¬ 
ing its SMP chipset in production and 
switched to Plan B, video-acceieiator chips 
for PCs. C&T was unlucky enough to ac¬ 
tually pul MPAX into production, at which 
time its customers discovered tiiat the desk¬ 
top x86 SMP market was good for 17 units 
a year. C&T tried to sell off MPAX but in 
the end gam the prtxluct away. (You can 
read more about MPAX in Microprocessor 
Report, February 21, 1990.) 

Had that S3 interview transpired, I 
would have been correct in my assess¬ 
ment of S3’s original target market. Be¬ 
ing right wouldn’t have helped, there 
would been little radioactive bits of me 
spread all over Silicon Valley. At die time, 

I had a lot of experience designing frame 
buffers using video controllers and that's 
the field S3 entered with great success 
shortly thereafter. We just never made 
connections. 

Recently, a small but profitable niche 
market has developed for SMPs as web 
servers. As I write tills, two PC magazines 
have reviews of these quad-P6 .servers in 
their current issues. Prices range from 
$30K to $36K. CoroUary Inc. has just an- 
nounced an 8-CPU x86 SMP moiherboard 
controller chipset called "Profusion.” NCR 
is even getting into the 8-CPU aa with a 
proprietary memory controller called 
"OctaScale." To kill a really bad idea, you 
have to drive a wooden stake through its 
heart and bury it at midnight in a ctoss- 
road. Say, the intersection of Tasman and 
Great America. C53's main plant is only 
a block away.) 

SMPs: A Great Ideo! 

Like mast of you, 1 like the idea of SMPs. 
I even toyed with producing one back in 
the days when I was running DTACK 
Grounded. Fd love to liave a quad-P6 SMP 
for some artificial neural net back-propa¬ 
gation experiments, but I won't pay $30K 
to get one. Jean-Louis Gassee's BeBox is 
widely admired but not purchased. 

A colleague of mine in Rhode Island 
also likes SMPs, but he tliinks tlie future 
of SMPs is on a single die. Why, he rea¬ 
sons, expend 15 million transistors on a 
single CPU when you can instead put four 


A small but profitable 
nkhe market 
has developed 
for SMPs as web 
servers 


CPUs with 3-75 million transistors each on 
tliat die? Lots of smart folk share his opin¬ 
ion here in Silicon Valley. In fact, when 
DEC introduced its Alpha microprocessor 
in 1992, it announced that over ten years 
the cliip would evolve into a single-chip 
SMP with up to ten CPUs on board] Alas, 
four of tliose ten years have elapsed and 
Alpha is still a uniprocessor architecture. 
And a 15^ mil I ion-transistor CPU has, in 
fact, been introduced—IBM’s P2SC, with 
i28-KB data and 32-KB instruction caches 
and (get this) a 256-hit data bus! It's a 
uniprocessor. 

This column is inspired by the special 
August 5i 1996 Microprocessor Report, 
which celebrates the 25 th anniversary of 
the microprocessor and contains articles 


discussing the future of microprocessing. 
One of these articles, by DECs Richard 
Sites, confesses the "failure'' of the Alpha 
SMP plan (the Alpha architecture is doing 
very well indeed, thank you, as a unipro¬ 
cessor). 

The article by University of Michigan 
researcher Yale Patt focuses entirely on 
the issue of uniprocessing versus SMP. He 
points out tliat we're coming up on a bil¬ 
lion transistors per die— that's 180 P6 
equivalents— and poses this question: 

If the design point is performance,.. Is it 
better to partition the billion tnin.sLstors into 
smaller units and implement a multipro¬ 
cessor on a diip, or to build a very wide 
VLIW uniprocessor [or implement other 
SMP configurations!? ..At the level of 100 
million transistors, the answer is very clear 
to me: use tlie tiansistois in a uniproces¬ 
sor.., At 100 million transistors, I don’t be¬ 
lieve we have at all run out of steam in 
things we can add in support of a single 
instnjction stream. At one billion transis¬ 
tors, the question is less easy to answer 
cavalierly. Still, I think I would opt for a 
yet more pow^erful uniprocessor. 

I think it'll be a long, long time before 
my Rhode Island colleague has a one- 
die SMP in his desktop computer. Per¬ 
haps in his next incarnation, or the one 
after that. (Twenty-Ove years elapsed be¬ 
tween the 2260-imn.sistor Intel 400^ and 
the IS-million transistor IBM P2SC. Tliat’s 
a 6637:1 increa.se in the number of tran¬ 
sistors. 1b get from the P2SC to a billion- 
transistor CPU, the step Is only a tenth 
as large. A 100-million-transistor CPU? 


Transistor Count: 2260to 15 militon 

doubling time =1,969 years 

5.39 years to CPU_,100M, 11,93 years to CPUJ B 

Die Size: .0165 to .525 square inches 
doubling time = 5.01 years 

CPU_100M = 1.1 sq in, CPU_1B = 2.74 square inches 

Design Rules: 10 microns to 0.29 microns 

halving time = 4.89 years 

CPU^IOOM ^ .136u. CPU_1B = .0535u 

Clock Rate: 750 KHz to 135 MHz 

doubling time = 3,34 years 

CPU_100M = 414 MHz, CPU^IB = 1.61 GHz 

Bus Width: 4 bits to 266 bits 
doubling time “ 4.17 years 

CPU_100M = 627 (512) bits, CPU_1B = 1862 {2048?) 

Pin Count: 16 pins to 1038 “pins” BGA* 

doubling time = 4.11 years 

CPUJGOM = 2702 ‘pins," CPU_1B ^ 8150 "pins” 


Table I: 100-million and 1-billion transistor CPU trends using the Intel 4004 
and IBM P2SC microprocessors as base data. *BGA=BaU Grid Array. 
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Tlie step is a hundredth as large. Pro¬ 
fessor Pat Us scenarios aren't all that 
bizarre or far out j 

The baiefiLs of SMPs as server engines 
is easy to explain. Tom, Dick, and Harry 
want to access a web site at die san^ time. 
One of the SMP’s quad CPUs Ls assigned 
to each, with a CPU in reserve in case Irv¬ 
ing logs in. 

the attraction of genera I-ptjrpose SMPs 
is easy to explain. Four CPUs have four 
times the number-crunching power (for 
instance) of one CPLI. But...there are fa¬ 
tal software and hardware problems: In 
general, applications cannot be parti¬ 
tioned easily (think of word processing). 
And there's a massive bottleneck at the 
memory interface (think of a drag-racer 
w'itli a 5000-hp engine and a VW trans- 
mis,sion). 

Projections, Not Predictions 

1 like to take bng-standing uends and pro¬ 
ject them. I'm going to take this opportu¬ 
nity to describe tlie 100-million and 1-bil¬ 
lion transistor CPU. ITie numbers in Table 
1 aren't something I grabbed out of a hat; 
tliey're printouts from a simple QuickBa- 
sic program that manipulates log-linear 
graph data. I’m using 25 years and the In¬ 
tel 4004 and IBM P2SC microprocessors 
as the i>ase data. 

Lei me say thi.s again: The numbers in 
T’able 1 are not predictions. They are pro¬ 
jections based on 25-year trends as de¬ 
fined by just two microprocessors. How¬ 
ever, all of tliese parameters have, in fact, 
been steadily progressing at a substan¬ 
tially constant rate over die past 25 years. 
If the trends hold, the table's numbers are 
golden. 

Everybody's favorite trend-buster is the 
design mies. At diis time, 0.135 microns 
looks iffy and 0.0535 microns looks ex¬ 
tremely iffy, But as reccTitly as five years 
ag^i, today’s 0.29 microns didn’t seem pos¬ 
sible without going to X-rays for mask 
projection. 

In my previous column, a very steady 
17-year memory price trend was graphed. 
The plot (and the DRAM market) went 
bonkers when tlie U.S. government, in its 
infinite wisdom, stepped into the DRAM 
market. Maybe the CPU trends will con¬ 
tinue for anodier 12 years. If not, it might 
not be a technical problem that proves 
tlie stopper. Our government is here to 
help us... 

Looking back, I realize I liad the wrong 
movie set in mind. Instead of a giant Man¬ 
tis, a flowing river of—^ not army ants, bui 
voracious desktop computers—would ap¬ 
pear, devouring ever^^ng in sight, in¬ 
cluding entire industries. 

DDJ 


60 


Dn Dobb^s Sourcebook^ NoiTemberlDecember 1996 















SOFTWARE AND THE LAW 



Doing Business on the Net 


T he Internet may be the most im¬ 
portant new business frontier in 
coming years. It offers instant ac- 
cesSj an mtemational customer base 
of unparalleled size, a promotional medi¬ 
um more powerful than television, and 
sales without salespeople. For sofi\vare 
vendors, tlie Internet Ls particularly allur¬ 
ing because it can deliver software almost 
instantly. And all of this comes at essen¬ 
tially no cost. 

But the very attributes that provide so 
much new' opportunity also markedly ac¬ 
centuate the legal risk. Unlike traditional 
marketing channels, tJiere Ls little customer 
contact, often nothing done writing,” 
a mechanism which does not dLstinguish 
between a customer down the street and 
halfway around the world, and a system 
which operate,s among the silence of ma¬ 
chines without human intervention. WliiU 
you do on the Internet is also extremely 
visible. 

While the technological changes are 
continuing at a feverish pace, the legal 
system is trying to catch up. As it always 
does, the law tries to decide new ques¬ 
tions based on the answers to old ones. 
Sometimes it works, sometimes it doesn't. 

But companies braving this new fron¬ 
tier cannot wait. For them, here are some 
important It^al guidelines. 


Marc is a patmt attorney and sharehold¬ 
er in the intellecwal-property law firm of 
Poms, Smith, Lande, & Rem in LosAngel^, 
CA. Marc specializes in computer law and 
can be contacted at 73414.1226®com- 
puserve.com. 


Marc E. Brown 


Avoiding Infringement 

Infringing a patent, copyright, trademark, 
or trade secret is one of the fastest ways 
to bring a new business venture to a crash¬ 
ing halt. Injunctions profiibiting infringing 
sales can be obtained in a matter of days. 
Tlie cost of a lawsuit can drain a compa¬ 
ny of the capital it needs to survive. Cus- 
tomers and prospective customers are of¬ 
ten direatentil, badly miiiring any goodwill 
that matkeiing efforts have established. 

Patents present one of the greatest risks. 
There are patents claimed by their own¬ 
ers to broadly cover technologies in com¬ 
pression, encryption, and database access. 
There is even a company (E-Data) that 
owns a patent allegedly covering the con- 
cept of selling software over the Internet. 
The patent tlireat is heightened by the fact 
tliat ignorance of die patent or indepen¬ 
dent creation of the technology is no de¬ 
fense. Patents on software are also be¬ 
coming more prevalent. 

If you are hoping that I can now^ tell 
you how to avoid all of these problems, 
you are in for disappointment. TTiere re¬ 
ally is no economical w^ay to do so. Ah 
tliough an attorney can be hired to per¬ 
form an “infringement search,” die search 
is usually limited to one or two features 
that the client suspects might be covered 
by a patent. But today's technology is ad¬ 
vancing so quickly tiiat each new prod¬ 
uct often contains dozens of innovative 
features, making the cost of a compre¬ 
hensive search prohibitive. (Typically, a 


few thousand dollars is required to search 
a single feature.) 

But there are things you can and should 
do to minimize risk. Careful attention 
should be paid to trade publications that 
trumpet news of threatening patents. 
Copies of these patents should be ob¬ 
tained and studied, (For help, see my col¬ 
umn ''Determining Software Patent In¬ 
fringement in the January/February 1996 
Dr Dohb's Sourcehook) Frequently, the 
technology can be changed to avoid the 
patent; a license can he purchased for a 
livable price; or a defense coalition with 
other companies can be formed. 

Software is also protected by copyright 
law. Protection will usually be afforded, 
even if tiiere is no copyright notice or reg¬ 
istration. Unlilte patents, however, a copy¬ 
right cannot be infringed by independenlly 
created teclmology. Copying of a sub¬ 
stantial portion of the copyrighted code^— 
or at least its underlying algorithms^—Is 
usually required. 

To avoid copyright infringement, you 
simply need to be careful. You also need 
to remember tliat the childhood limerick 
"finders keepers, losers weepers” has no 
place in copyright law. Just because you 
pick up a graphic image, text file, or seg¬ 
ment of code over the Internet does not 
mean that you can display it or send 
copies to others from your web site. If 
you do, you probably will be infringing 
a copyri^t. 

A more subtle piioblem arises when you 
use portions of material provided by oth¬ 
ers under the erroneous assumption that 
you have their permission. Most software 
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Source Codelindex 
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Sourcecode-over a milli on lines 

Here it is. The most comprehensive 
collection of DDJ source code ever-^ll on 
one CD-ROM. You get over 10 1/2 years 
of DDJ code (January 1 986 to August 
1996). And you get more than just the 
code-weV© also included all the executa¬ 
bles and binaries in languages ranging 
from C+-^ to Moduta-3. Includes code from 
both Dr Dobb's Journal and Dr Dobb's 
Sourcebooks. 

Comprehensive Index 

And what would you do with all this 
source code if you didn't know what it 
was for. That's why we've included this 
user-friendly index that spans from 
January 1982 to August 1996. Get quick 
access to the DDJ material. Search by 
author and subject. Go from one topic to 
another using the hyper linking capabilities 
of this powerful and comprehensive index! 
Browsing and searching features as well 
as guidelines on how to navigate the sys¬ 
tem make this an invaluable tool for every 
programmer. 


ClUi TOLL fiS: 800 587-8319 
INTL Use man, rax, e-mail, w call 913-S41-IB3I 
FAX: 913-841-a24 
E-IIIUt:n<deps@iin.cfln 

Mai oners: 

Dr. Dihb's CD-ROM library 
1601 West Z3rd Street, Ste. ZOO 
Lawrence, KS 60046-2700 USA 


Visit the Dn Dobb's GD-flOIVI Library website! 

WWW. dd) .com/cdrom/ 


incorporates underlying libraries, pro¬ 
grams, or algorithms written by another 
company, Ju,st because you paid money 
for it, however, does not necessarily mean 
that you are free to dLsplay it on your web 
site or send copies of it to others. Most 
likely, the transaetion was accompanied 
by a iicense agreement" tliat imposed nu¬ 
merous restrictioas on what you could do. 
These need to he carefully reviewed to 
ensure that you are not exceeding the 
scope of the rights that were granted. 
When in doubt, try^ to get express per- 
mi.ssion for what you want to do. 

Trademarks are another fonn of inteb 
lectual jTroperty' that must l^e respected. In 
the United States, trademarks will be en¬ 
forced, cwen if they are not registcTed. They 
will also be enforced against innocent in¬ 
fringers who had no knowledge of tlieni. 

Tlie basic test for determining trade¬ 
mark infringement is whedier die name 
you have selected is likely to cause your 
software to lie confused as lieing manu¬ 
factured, sponsored by, or associated w ith 
another company. The similarity Ix^iween 
names is of obvious importance. Also im- 
fiortant is die similarity Ix^tween die prod¬ 
ucts, their promoticmal channels, and die 
sophistiaition of your customers. Under a 
law recently piLssed by Qingress, a famous 
Lrademark will often be enfc^rced against 
anyone who ""dikitcs" its significance, even 
T tliere is no “likeiihtKJd of confu.sion/ 

An issue somewhat uni<[ue to the Inter¬ 
net is wliedier a domain name am lie die 
sulTject of a imdemark infringement charge. 
Although the kiw in this area has not yet 
cryslallized, it seems clc*:ir diat the standard 
test of a ''likelilicxxl of confusion" and the 
protection alTcjided famous iiuirks against 
dilution wil] continue to apply. (For more 
information on diis suliject, ,see 'Trademark 
Wars in Cybei:space,” Dr. Dohh’s Source- 
^XKik, Novemix.T/[Xrcenit)er 1995. ) 

A quality "trademark clearance search" 
c'an be performed at relatively low cost 
(alxiut $3(K1), One of die most established 
companies performing such searches is 
’lliompson 8i Thompson (1-800-692-8833^ 
500 Viclory^ Road. North Quincy, MA 
02171-1545). One or two hours of attor¬ 
ney time is also usually needed to ana- 
lyza the true significance of the findings. 
A trademark clearance seardi should u.sii- 
ally be performed and analyzed before 
any significant amount of money is in¬ 
vested in promoting a new' name. 

The last funcLimental arai t^f intellectual- 
property protection is trade-secret pro¬ 
tection. Violation of diis type of right is 
rarely an accident. Usually, you know if 
your information Ls stolen. 

A more difficult question Ls w'hether you 
can extract algorithms and underlying con- 
CTepts by decompiling object code that you 
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lawfully obliiined from another company 
(by purchasing it on the open market¬ 
place, for example). A few months ago, 
most lawyers would have told you that 
you could, based on c^ourt dedsioos wliidi 
have held that decompilation does not 
constitute copyrigiit infringement. But die 
recent decision by the Court of Appeals 
in PwCD, Inc. v. Manbeu^ Zeidenherg Is 
making lawyers retliink this advice. 

Ifie trial court in ProCD allowed the de- 
fenckint to remarket the plaintiff s $10 mil¬ 
lion database of telephone numl:>ers with¬ 
out paying the plaintiff anything. The 
defender purcha.sed CD-ROMs contain¬ 
ing the database for about $150 on the 
open marketplace. Although accompanied 
by a shrink-wrap license that prohibited 
commercial use of the database, the trial 
court concluded that the shrink-wrap li¬ 
cense was unenforceable. 

The appellate court reversed. It con¬ 
cluded that die shi ink-wrap license was 
enforceable. Of partic\ilar importance to 
this discussion, the appellate court also 
concluded tliat die licem^ could impose 
restrictions beyond those provided by 
copyright law'. If the principals that un¬ 
derlie tliis new and important decision are 
broadly appHed, a clause in a shrink-w^rap 
licease prohibiting decompilation will also 
be enforced, making such reverse-engi¬ 
neering illegal. My advice is to respect any 
such clause and tc> expect trouble if you 
violate it, at least for now^ 

Protecting Intellectuol Property 

The flip side of die coin, of course, is to 
maximize protection for your software. 
Unlike most pnxluas, .software can lx? du¬ 
plicated at virtually no cost. Legal protec¬ 
tion Ls usually essential for effective com¬ 
petition. This is particularly true when 
software is distributed over the Internet, 
a medium that is unrestricted and unreg¬ 
ulated. 

Tlie available typ>es of protection are the 
same as diose you must exercise care not 
to infringe: patents, copyrights, trade se¬ 
crets, and trademarks. I will now briefly 
examine what yf>u need to do so secure 
these types of protecTion, But it is impor¬ 
tant to rememlier that tliese efforts will not 
lie effective in many countiies outside of 
tile United States, [f you choose to dlslribute 
your software over tfie LntemeE, some unau- 
tliorized duplication is inevitable. 

Patents are often ilie mast effective fomi 
of protection. Examine your sofrw^are for 
unique functional features diat you expect 
will give it a competitive edge. After do¬ 
ing a search to verify their novelty, apply 
for a patent on tliese features in the Unit¬ 
ed States. Do tins before disclosing the 
concept to others or l:>eginning any com¬ 
mercial use or marketing. (The United 
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States will alk^w tlie application to be filed 
up to one year later, but many countries 
will not,) Mer you file in the ifnited States, 
you have up to one year to extend your 
application into most foreign cciuniries. 

Be sure to give notice of any patent 
riglits you have. Place tlie notice on a web 
page, in a Readme file that acxximpanies 
the software, a boot-up screen for the 
software, and the online help file for the 
software. Notice of the patent's existence 
is also often quite beneficial in promo¬ 
tional materials. 

All modern software wall automatically 
l^e covered by copyright law , evcTi thougli 
you do not mark it w ith a copyright noticx^ 
or register ii Notwithstandirig, you sliould 
place a (c) followed by the year of first dis¬ 
tribution and die owner’s name in the cxxle 
and on the bcxjl-up scieen. You sliould also 
file an application to register your copyriglit 
wifliin three months after you first distribute 
it Tills will substintlally enhance the reme¬ 
dies you can olmin for its iniringanent Un¬ 
like patents, an application to register a 
copyright is inexpensive and easy to do 
yourself. You can obtain the application and 
instructions from the Copyriglit Office 
(http://lcwebdoc.gov/copyright/). You 
should also be sure to promptly register 
each significant upgrade. 


The use of an online 
license agreement 
is essential 


Trade secrets are protected widiout any 
type of registration. In addition to being 
a valuable secret, however, you usually 
must demonstrate iliat you took reason- 
alile steps to protea the .secrecy of the in¬ 
formation, Traditionally, tliis means phys¬ 
ical security measures and contractual 
commitments to protect the confidential¬ 
ity of the trade secrets by all tliose wdio 
come in contact with it, ,such as employ¬ 
ees and, particularly if they are given 
source code, customers. 

Trademarks are another useful form of 
protection. Like copyrights, no forniid reg¬ 
istration is necessary for protection in the 
United States, But like copyrights, prompt 
registration will usually provide addition¬ 


al remedies in die event of infringement. 
However, in many foreign countries (Ger¬ 
many, for instance), registration is a re¬ 
quirement for protection. If you do not 
promptly register your trademark in these 
foreign countries, someone else might reg¬ 
ister it first, then demand money from you 
for iLs continued use. 

Qmtractual restrictions are also impor¬ 
tant and may become even more impor¬ 
tant in view of the recent decision of 
FroCD, fnc. v. Zeidenberg. 

Export Restrictions 

Export restrictions are a particularly sticky 
area which few people understand. 

At present, export restrictions are prin¬ 
cipally imposed by three governmental 
agencies. The Uepartment of Commerce 
administers the Export Administration Reg¬ 
ulations under theii- Bureau of Export Ad- 
niinLstrations. The Department of Slate ad¬ 
ministers tlie International Traffic in Arms 
Regulations. Last, there is the Office of 
Foreign Assets Controls under the Trea¬ 
sury Department. 

All prcxluas sold outside of tliis coun¬ 
try {including software) require a Ecense 
under the Export Adminisinition Regula¬ 
tions, Most software automatically quali¬ 
fies for a “general license” without the 
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Dynamic Web Sites Made Easy! 

Your job is to bring people to your Web through powerful end kitoragliVe 
Web pages. ScriptEase:Webserver Edition help^ anyone Involved in site 

development quiddy create Web pages that promote heavy site traffic and 
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Remote IDE Debugger 


With ScliptEase:Webserver Edition's run-time error detection, bugs wont 
even get the chance to reach (or crash) your Web serverrln addition, our 
Remote Integrated Debugging Environment permits real-time debugging 
over the internet. From the browser client you can now debug scripts lind^by- 
Jhie and variabte-by-variable, as they execute remotely on your Web server 


True Multi-Plotforni Solution 


ScriptEase: Webserver ^dltlonis available fdya wide variety nf Web servers 
(through CGI. )SAPI, of other BGl) on a Wide variety of platforms (Windows 
/3.1/gS/MT, UNIX, SunOS, Solaris, OS/2, MacOS and Linux), No matter uyhich 
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Come visit us today at http;//www.rH3mbas.com/ and download your FREE 
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need for any type of application. Howev¬ 
er, there are still requirements for a “des¬ 
tination tx)ntrol statement” and a “shippers 
export declaration.” 

If software does not qualify for a gen¬ 
eral license, an application (Form BXA- 
622B) must be submitted for an “indi¬ 
vidually validated license.” Technical 
material may also have to be submitted. 
Such applications are granted on a case- 
by-case basis. 

To better understand this area, contaa 
the Bureau of Export Administration (202- 
482-4811). To determine your software’s 
classification, you may also need to ol> 
tain a copy of the Export Administration 
Regulations (202-275-2091). 

Encryption software will often require 
a valid exfx^rt license issued by the Office 
of Defense Trade Controls of the State De¬ 
partment under the International Traffic 
in Arms Regulations. The .sophistication 
of the encryption software will be a key 
factor. 

The Office of Foreign Assets Controls 
embarg(x?s exports to certain countries 
for political and other reasons. Tlie em¬ 
bargoed cx)untries currently include Cuba, 
Iraq, Libya, North Korea, and the former 
Yugaslavia. It appears tliat exports of any 
type of software to any of lhe.se coun¬ 
tries is currently illegal. What is not yet 
clear are what steps a U.S. company is 
required to take in order to comply with 
these restrictions in view of the world¬ 
wide access the Internet provides and 
the technical difficulties in restricting that 
access. 

At present, the White House and the 
Department of Commerce are reevaluat¬ 
ing these export regulations, particularly 
as they apply to encryption .software and 
the Internet. The existing rules and pro 
cedures simply do not fit the way busi¬ 
ness is (and must lx?) done on the Inter¬ 
net. An excellent source for more 
information about export regulations is 
Tradeport at http://www.tradeport.oig. 

The Online License Agreement 

Few retail stores require a cu.siomer to 
commit to an agreement IxTore he “pur¬ 
chases” software. But this is exactly what 
many software vendors are doing over 
the Internet, and it’s what you should 
be doing. 

The use of an online license agreemcTit 
that the buyer must “accept” before re¬ 
ceiving the software is essential. If prop¬ 
erly worded and implemented, it will sul> 
stantially enhance the protection the law 
affords to both the software and its ven¬ 
dor. It should also help overcome the 
problems with the enforceability of 
shrink-wrap licenses. Online license 
agreements should be used in connec- 


Encryption software 
will often require 
a valid export 
license 


tion with all software, including demo 

software, that is given away. 

Include language in the license agree¬ 
ment tliat addresses each of the following: 

• A statement that die .software Is being 
licensed, not sold. 

• Use restrictions, including restrictions 
on the number of cxipies, machines, and 
locations. Prohibitions agaiast decom¬ 
pilation and other types of reverse¬ 
engineering; interfaces with other .soft¬ 
ware; and modificatioas. 

• An acknowledgmcTit that the .softwaa* 
embodies tnide .secrets and a commit¬ 
ment not to extract these trade secrets, 
not to u.se them outside of the .software, 
and not to di.sclo.se them to others. 

• DLsclaimers, including disclaimers of the 
implied warranties of merchantability 
and fitness for a particular purpo.se, and 
di.sclaimers of con.sequential and indi¬ 
rect damages. 

• Remedy restrictions; for example, a 
clause restricting a buyer’s remedy for 
any defect to simply a purcha.se-price 
refund. 

• A disclosure and warning about any 
lype of “time lx)mb” that will c'au.se the 
.software to cua-se functioning after a cer¬ 
tain amount of time if money (or addi¬ 
tional money) is not paid. (Never im¬ 
plant a “time lx)mb” that damages ckita.) 

• Export repre.scutations, including rep- 
rescTitatioas that the software Ls not Ix;- 
ing purcha.sed by and will not be de- 
liverkl to any lx)ycotted cxntntry, as well 
as any other language required by the 
particular export licease being u.sed. 

• Designation of the governing law; for 
example, that the transaction will be 
govemcxl by the laws of liie State of Cal¬ 
ifornia (except as otherwi.se provided 
by the United States Conventions for 
Contracts for the International Sale of 
Goods) and that any claim will be ex- 
clu.sively resolved thiough arbitration in 
the State of California. 

• Entire agreement; for instance, a clause 
stating that tliere are no other terms to 


the agreement and that the buyer is not 
relying upon anything not stated in the 
agreement. 

All language in the license agreement 
should be simple and clear. 

The manner in which the online license 
agreement is implemented Ls also of great 
importance. It should be presented to the 
buycT before any software is provided and 
before the buyer cx)mmits to making pay¬ 
ment. The buyer should be required to 
pre.ss an “accept” button, by which he ac¬ 
knowledges that he has read all of the 
terms of the agreement, understands these 
terms, and agrees to abide by them. The 
buyer should also be provided with a 
means to refuse the license, such as a No 
or Cancel button. 

Before allowing buyers to communicate 
their acceptance, information about buy¬ 
ers should be required, .such as name, 
company name, address, and .so on. Such 
information is also of obvious value in 
conneaion with upgrades, notices, new 
products, and the like. 

Lastly, provide buyers with documenta¬ 
tion of the agreement. Place the terms of 
the buyer’s agreement in a Readme file or 
in .some otlier file received with the .soft¬ 
ware. If po.ssible, make the terms of the 
agreement accessible from witliin the soft¬ 
ware during its operatic^n (as an item in die 
Help menu, for example). Mailing a hard 
copy to the buyer Ls also a gcxxl practice. 

Other Issues 

For reasons I have not yet l)een able to 
understand, my editor has not yet alkxved 
my columns to occupy thus entire maga¬ 
zine. Equally .surprising Ls that my .secre¬ 
tary .seems unwilling to type forever. 

The Ixittom line is that I extn’t say any¬ 
thing more right now. But I will flag a 
few other issues relevant to busine.ss on 
the Internet: 

• .Strucluring a payment system that en¬ 
sures the receipt of payment. 

• Obtaining nece.s.sary busine.ss licen.ses. 

• Tax con.sequences. 

• Tile legal form of your business (corpo¬ 
ration, partnership, dba, or whatever). 

• Defamation. 

Conclusion 

The Internet is mo.st definitely our newest 
busine.ss frontier. As with all pioneering, 
great opportunity Ls balanced by equally 
great risk. So, as you brave diLs new world, 
lie sure to give coasideration to the legal 
Ls.sues that 1 have raised. An ounce of pre¬ 
vention is wortli a pxiund of cure, partic¬ 
ularly on the Net. 

DDJ 
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Introdiicing PX PRO, a cro^s-platform 
visual neose environmerrt thaft speeds 
applicatiort development and makes other 
OUl builders obsolete. PRO includes a 
full-blown, integrated €+■¥ framework that 
promotes neuse, letting you biftz through 
new application development. Also 
included is a 27-widget neuseable library 
with graphs, Windows^ 95-iike controls, 
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It even lets you get started In Jav^^ 
3X PRO isn't just for prototyping. We 
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projects. And you can deploy applications on 
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m Optional visual database development 

• Supports G, C++, and Java deveiopmeiit 
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http: / /WWW. ics.com/products/BXPRO 



Intagrated Computer 
Solutions Incorporated 














































